[Refactoring] Extract distinct responsibility zones from workdir-setup.ts

[github-actions]

Refactoring Opportunity

Summary

• File: src/workdir-setup.ts
• Current size: 397 lines
• Responsibilities identified: 5 distinct concern zones
• Largest function: prepareLogDirectories() at 116 lines (lines 144–260)

Evidence

workdir-setup.ts conflates five conceptually distinct responsibilities:

Lines	Responsibility
16–119	Low-level directory utilities — ensureDirectory, assertRealDirectory, createMissingOwnedDirectorySegments
120–143	Chroot mount helpers — prepareChrootHomeMountpoint
144–260	Log directory setup — prepareLogDirectories (116 lines: agent-logs, session-state, squid-logs, api-proxy-logs, MCP logs — each with UID/chown logic)
261–364	Chroot home mounts — pruneStaleMcpLogDirs, prepareChrootHomeMounts (handles home-dir allowlisting, runner tool cache, Docker socket)
365–397	Init signal / work directory orchestration — ensureInitSignalDir, prepareWorkDirectories

The prepareLogDirectories function is 116 lines because it repeats a chown pattern for each log type (agent-logs, session-state, squid-logs, api-proxy-logs, cli-proxy-logs, MCP logs). This repetition could itself be reduced by a shared helper.

Proposed Split

src/workdir-setup.ts (397 lines) could be refactored as:

• src/fs-utils.ts — ensureDirectory, assertRealDirectory, createMissingOwnedDirectorySegments (~104 lines; general-purpose, reusable)
• src/chroot-home-setup.ts — prepareChrootHomeMountpoint, prepareChrootHomeMounts, pruneStaleMcpLogDirs (~180 lines; chroot-specific logic)
• src/log-directory-setup.ts — prepareLogDirectories and its per-type chown helper (~120 lines)
• src/workdir-setup.ts — thin orchestrator: ensureInitSignalDir, prepareWorkDirectories (~40 lines)

Alternatively, a lighter approach: extract a shared ensureOwnedDirectory(path, uid, gid) helper to eliminate the repeated chown pattern inside prepareLogDirectories, reducing it from 116 to ~40 lines.

Affected Callers

grep -rn "from.*workdir-setup\|require.*workdir-setup" src/ --include="*.ts"

Current callers:

• src/config-writer.ts:20 — imports prepareWorkDirectories
• Test files: src/workdir-setup.test.ts, src/coverage-improvements.test.ts

Effort Estimate

Medium — involves moving internal functions across files and updating test imports.

Benefits

• General filesystem utilities become independently testable and reusable
• Chroot-specific logic is isolated from log-path management
• prepareLogDirectories can be simplified by a shared owned-directory helper
• Smaller files reduce cognitive overhead when debugging permission issues across deployment topologies (standard, ARC/DinD, rootless Docker)

---

Detected by Refactoring Scanner workflow. Run date: 2026-07-08

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by Refactoring Opportunity Scanner · 186.6 AIC · ⊞ 6.7K · ◷

• expires on Sep 6, 2026, 5:32 AM UTC