Skip to content

fix(orch): resilient worktree reset and better failure UX - #12

Merged
HenryLach merged 32 commits into
mainfrom
feat/polyrepo-support
Mar 15, 2026
Merged

fix(orch): resilient worktree reset and better failure UX#12
HenryLach merged 32 commits into
mainfrom
feat/polyrepo-support

Conversation

@HenryLach

@HenryLach HenryLach commented Mar 15, 2026

Copy link
Copy Markdown
Owner

Problem

Batch execution failed at wave 3 because a file named nul (Windows reserved device name) was left in the worktree by an agent. This caused a cascade:

  1. git clean -fd failed (can't delete nul on Windows) → safeResetWorktree returned failure
  2. Fallback removeWorktree also failed (git had partially deregistered the worktree)
  3. Next wave couldn't create worktrees → wave 3 failed → 6 downstream tasks blocked

Fixes

Resilient worktree reset — safeResetWorktree() now checks git status --porcelain after cleaning instead of treating the git clean exit code as fatal. If only untracked files remain (like undeletable nul), the reset proceeds.

Force cleanup fallback — New forceCleanupWorktree() function as last resort when both reset and remove fail. Force-removes the directory (rd /s /q on Windows), prunes git state, and deletes the lane branch.

Better failure UX — Batch failure message now shows actionable next steps (/orch-status, /orch-resume, /orch-abort) and explains blocked task count.

Testing

  • 53/53 worktree lifecycle tests pass
  • CLI doctor passes

HenryLach added 30 commits March 15, 2026 01:37
@HenryLach
feat(TP-001): add workspace mode types, ExecutionContext, and validat…
e5c207e 
…ion error contracts

- WorkspaceMode ('repo' | 'workspace') with mode determination rules
- WorkspaceRepoConfig, WorkspaceRoutingConfig, WorkspaceConfig interfaces
- ExecutionContext with workspaceRoot/repoRoot separation
- WorkspaceConfigErrorCode (12 stable error codes) + WorkspaceConfigError
- createRepoModeContext() factory for repo-mode defaults
- WORKSPACE_CONFIG_FILENAME constant and workspaceConfigPath() helper
- Full JSDoc documenting mode behavior invariants
@HenryLach
feat(TP-001): implement workspace config loading and validation
283b3f6 
- Create extensions/taskplane/workspace.ts with full validation chain
- loadWorkspaceConfig(): null when no config (repo mode), throws WorkspaceConfigError on invalid
- canonicalizePath(): Windows-safe path normalization matching worktree.ts pattern
- buildExecutionContext(): unified context builder for Step 2 wiring
- Deterministic validation order with all 12 WorkspaceConfigErrorCode branches
- Per-repo git root validation via git rev-parse
- Duplicate repo path detection after canonicalization
- Routing validation: tasks_root existence, default_repo reference check
@HenryLach
feat(TP-001): add workspace module to barrel export in index.ts
8c52d1f
@HenryLach
checkpoint: TP-001 Step 1 complete, verified in iteration 2
40369da
@HenryLach
checkpoint: TP-001 Step 2 complete, verified in iteration 3
17ed0ba
@HenryLach
fix(TP-001): use repoRoot consistently for state/discovery/abort paths
2a433a6 
Address R006 findings: extension.ts was using workspaceRoot for .pi state,
orphan detection, batch state, abort signal, and discovery, while engine.ts,
resume.ts, and execution.ts use repoRoot (aliased from cwd). This created a
split where abort signals and state files could be read/written to different
paths in workspace mode.

Fix: use repoRoot for all operations to match engine/resume/execution.
In repo mode this is a no-op (workspaceRoot === repoRoot).
TODO comment added for future workspace-mode state root splitting.
@HenryLach
checkpoint: TP-001 Step 2 R006 fix applied, repoRoot used consistently
65bee84
@HenryLach
test(TP-001): add workspace config test suite (38 tests) and complete…
9758a96 
… Step 3 verification
@HenryLach
feat(TP-001): complete Step 4 documentation and delivery
8417e7e 
- Updated polyrepo-support-spec.md with TP-001 delivery status, schema
  adjustments, and Phase 1 checklist
- Updated polyrepo-implementation-plan.md marking WS-A as delivered,
  PR-1 complete, readiness checklist updated
- Reviewed docs/reference/commands.md — no user-visible changes
- Logged 5 discoveries in STATUS.md
- Created .DONE marker
@HenryLach
merge: wave 1 lane 1 — TP-001
79c7bd3
@HenryLach
feat(TP-002): parse execution target metadata from PROMPT.md (Step 0)
4fd2ea4 
- ParsedTask.promptRepoId?: string field in types.ts
- Section-based parser: ## Execution Target with Repo: line
- Inline parser: **Repo:** <id> fallback
- Precedence: section > inline, repo ID validated against /^[a-z0-9][a-z0-9-]*$/
- Backward compat: missing metadata = undefined, no error
- 28 tests in discovery-prompt-parser.test.ts (all pass)
@HenryLach
checkpoint: TP-002 Step 0 complete — hydrated plan, improved tests (2…
eed933d 
…4 passing)
@HenryLach
feat(TP-002): implement routing precedence chain (Step 1)
b6c1ab3 
- resolveTaskRouting() applies 3-level precedence: prompt → area → default
- Wire workspaceConfig through runDiscovery, executeOrchBatch, resumeOrchBatch
- Add FATAL_DISCOVERY_CODES constant for DRY fatal-error classification
- Add TASK_REPO_UNRESOLVED/TASK_REPO_UNKNOWN error codes
- Update engine.ts and extension.ts to use FATAL_DISCOVERY_CODES
- 14 routing tests (categories 8.x-14.x), all 38 routing tests pass
@HenryLach
checkpoint: TP-002 Step 1 verified — routing precedence, error codes,…
a9f1bb1 
… call-site plumbing confirmed
@HenryLach
feat(TP-002): annotate discovery outputs with repo routing
91fe024 
- Parse repo_id from task-runner.yaml into TaskArea.repoId (config.ts)
- Annotate formatDiscoveryResults pending tasks with resolved repo
- Add routing-specific guidance to /orch-plan and /orch fatal abort
- Add 13 tests: config parsing, output annotation, guidance text
@HenryLach
checkpoint: TP-002 Step 2 verified — all 68 routing + 40 workspace te…
5130b0d 
…sts pass
@HenryLach
checkpoint: TP-002 Step 3 complete — 108 targeted tests pass, 23 pre-…
63f99e1 
…existing failures confirmed unrelated, CLI smoke OK
@HenryLach
feat(TP-003): introduce resolveCanonicalTaskPaths for external task f…
f584d22 
…older support

Add canonical task-path resolver that correctly handles both:
- Repo mode: task folder inside repoRoot → worktree-relative path
- Workspace mode: task folder outside repoRoot → absolute path (external)

Refactored resolveTaskDonePath, parseWorktreeStatusMd, and
pollUntilTaskComplete to delegate to the new single-source-of-truth
resolver. Archive fallback preserved for both branches.

Deferred: abort.ts selectAbortTargetSessions (Step 1 scope).
@HenryLach
checkpoint: TP-003 Step 0 complete — canonical task-path resolver imp…
e253f10 
…lemented and verified
@HenryLach
fix(TP-003): refactor abort.ts to use canonical task-path resolver fo…
ce69217 
…r external task folders
@HenryLach
fix(TP-003): clarify buildLaneEnvVars external path comment for works…
9ab18c9 
…pace mode
@HenryLach
checkpoint: TP-003 Step 1 complete — completion probing fixed for ext…
af4b558 
…ernal task folders
@HenryLach
test(TP-003): add regression tests for resolveCanonicalTaskPaths path…
40c5b98 
… resolution

Add execution-path-resolution.test.ts with comprehensive coverage:
- Monorepo: task folder inside repo root translates to worktree path
- External/workspace: task folder outside repo uses absolute path
- Archive fallback for both monorepo and external paths
- resolveTaskDonePath delegation correctness
- Edge cases: prefix overlap, backslash paths, multi-lane resolution,
  same canonical path for external across worktrees
@HenryLach
test(TP-003): add regression coverage for external task folder path r…
9629986 
…esolution

29 tests covering four resolution branches of resolveCanonicalTaskPaths:
- repo-contained (monorepo) → worktree-relative resolution
- external (workspace) → canonical absolute resolution
- archive fallback when primary missing
- primary-path fallback when no files exist

Plus downstream call-site coverage:
- resolveTaskDonePath delegation
- parseWorktreeStatusMd canonical path usage
- selectAbortTargetSessions abort-flow regression (6 cases)
- monorepo completion detection regression (4 cases)
@HenryLach
docs(TP-003): update polyrepo-implementation-plan with path-resolutio…
d54c1ef 
…n strategy; complete Step 4 documentation
@HenryLach
feat(TP-008): detect workspace mode in doctor diagnostics
0c29105 
- Add loadWorkspaceConfigForDoctor() with line-based YAML parser
- Add workspace mode banner showing repo count, default repo, tasks_root
- Handle invalid workspace config as FAIL with error code and remediation hint
- Workspace root non-git does not trigger false negatives
- Repo mode output unchanged when no workspace config exists
@HenryLach
checkpoint: TP-008 Step 0 complete — workspace mode detection verified
7c1312e
@HenryLach
feat(TP-008): validate repo topology and area routing in workspace do…
a30a7db 
…ctor

- Extend discoverTaskAreaMetadata() to extract repo_id per area
- Add repo-path existence and git-repo validation in cmdDoctor()
- Add area repo_id routing validation against known workspace repos
- Gated on workspace mode + valid config; repo mode unchanged
- All verification scenarios pass: missing path, non-git, unknown repo_id
@HenryLach
feat(TP-008): improve operator guidance with actionable hints and R00…
ee657b7 
…4 fix

- Fix repo_id trim/truthy alignment: whitespace-only repo_id values no
  longer produce spurious AREA_REPO_ID_UNKNOWN failures (aligns with
  orchestrator config.ts behavior)
- Sort knownRepoIds for deterministic hint output in area routing errors
- Add consolidated 'Run: taskplane init' hint after missing config files
- Improve WORKSPACE_REPO_NOT_GIT hint with both git init and config fix
  remediation options
- Verified repo-mode output unchanged when all checks pass
- All pre-existing test failures confirmed unrelated to changes
@HenryLach
checkpoint: TP-008 Step 3 complete — testing & verification passed
b927cdd
@HenryLach
merge: wave 2 lane 1 — TP-002, TP-003, TP-008
da9b48c
@HenryLach
fix(orch): resilient worktree reset and better failure UX
4c32df0 
Three fixes for batch execution reliability on Windows:

1. safeResetWorktree: git clean -fd failures are no longer fatal.
   After cleaning, check git status --porcelain instead of the exit
   code. If only untracked files remain (e.g., undeletable Windows
   reserved names like 'nul'), proceed with the reset anyway.

2. forceCleanupWorktree: new last-resort recovery function. When both
   safeResetWorktree and removeWorktree fail, force-remove the
   directory (with Windows rd /s /q fallback for reserved names),
   prune stale git worktree refs, and delete the lane branch.
   Applied in both engine.ts and resume.ts fallback paths.

3. Batch failure message: show actionable next steps (orch-status,
   orch-resume, orch-abort) and explain blocked task count instead
   of just 'Batch failed'.
@HenryLach
HenryLach merged commit 5a32c8e into main Mar 15, 2026
1 check passed
@HenryLach
HenryLach deleted the feat/polyrepo-support branch March 15, 2026 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@HenryLach