harness-tools/docs/workflow/bash-worktree-cwd-record.md

Bash worktree cwd workflow record

Status

• Status: active
• Current phase: 8. Integrate locally
• Next safe action: verify the clean source checkout and fast-forward main to the approved feature branch.

Request and scope

• Request: address the first repository TODO so Bash execution honors the current Pi tool context inside hidden Git worktrees.
• In scope: reproduce the Pi 0.84.4 behavior; add a repository-owned, publishable @jbcode/pi-bash-cwd extension with an optional cwd tool argument resolved from the live session context; delegate command execution to Pi's built-in Bash implementation; test workspace-root, nested-package, relative-path, and missing-directory execution in a disposable hidden worktree; update package inventory and documentation; remove the resolved TODO.
• Out of scope: upgrading Pi, installing or publishing the new package, deploying, pushing, or modifying live/production data.

Git identity

• Source branch: main
• Base commit: 7e7cfdb5cb0e1a1218b9a2c8250267d5099637fc
• Feature branch: feature/honor-bash-worktree-cwd
• Worktree: /srv/data/code/jb-pi/harness-tools/.worktrees/honor-bash-worktree-cwd
• Omitted source changes: none; source checkout was clean and equal to origin/main after git fetch origin main.

Acceptance criteria

• @jbcode/pi-bash-cwd overrides the built-in bash tool with one backward-compatible optional cwd argument while preserving the existing command, timeout, output, truncation, cancellation, session-environment, and renderer contracts.
• Absolute and relative cwd values resolve from the live session ctx.cwd; omitted cwd retains the session directory.
• The requested directory is validated before delegating command execution.
• A regression test executes pwd from both a disposable hidden worktree root and a nested workspace package directory and observes the requested directory.
• A missing requested working directory fails before the shell command can create a sentinel side effect.
• Package inventory, README guidance, and the upstream Pi 0.85.0 packaging blocker TODO are synchronized.
• Existing repository typecheck and test suites pass.
• The resolved Bash cwd TODO and temporary workaround language are removed or updated without changing unrelated historical evidence.

Approved implementation plan and gates

• Plan/specification source: user request, docs/todos.md, and upstream Pi 0.84.4/0.85.0 source under /srv/data/opensrc/repos/github.com/earendil-works/pi/.
• Exact plan: (1) keep extensions/bash-cwd as the approved publishable package; (2) replace the built-in Bash schema with its existing command and timeout fields plus optional cwd; (3) resolve relative cwd from ctx.cwd, validate that the result is a directory, and only then construct and invoke Pi's built-in Bash definition for that directory; (4) preserve built-in rendering, prompt metadata, output, timeout, cancellation, truncation, and session environment by spreading and delegating to the host definition; (5) revise the regression to pass explicit absolute and relative cwd arguments while the session context remains the primary fixture checkout, covering hidden-worktree root, nested package, omitted cwd, and fail-before-sentinel cases; (6) retain approved package inventory/docs/full-verification work and record that Pi 0.85.0's separate ctx.cwd correction does not add this per-call argument.
• Plan approval: approved by the user through ask_user on 04SEP2026 (approve explicit cwd argument).
• UI classification and direction approval: non-UI; no prototype gate applies.
• Risk decisions and scope: the Pi dependency upgrade remains abandoned. The corrected tool schema adds one optional, backward-compatible field and uses the repository's existing typebox dependency. The package remains repository-only and will not be installed, published, or added to the active global Pi environment in this task.

Ownership

Assignment	Owner identity	Deadline	Exclusive paths	Before/after Git evidence	Outcome
Workflow setup and research	parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87	15 minutes	workflow record only	Before: clean main at 7e7cfdb; after: clean feature worktree at 5f853dc	Complete
Initial dependency-plan implementation	parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87	15 minutes	package.json, bun.lock, focused test, workflow record	Before: clean feature worktree at 9d68d5f; after: Pi 0.85.0 upgrade restored; focused red test retained unstaged	Paused and replanned after upstream packaging blocker
Local override implementation	parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87	15 minutes	extensions/bash-cwd/**, scripts/bash-cwd.test.mjs removal, package.json, scripts/package-workspaces.test.mjs, README.md, docs/npm-packages.md, docs/todos.md, docs/workflow/skill-led-development-workflow-plan.md, workflow record	Before: feature worktree at 3d68f7c with inspected product changes; after: clean product commit 328faa0	Complete
Review remediation cycle 1	parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87	15 minutes	extensions/bash-cwd/index.ts, extensions/bash-cwd/index.test.ts, extensions/bash-cwd/README.md, workflow record	Before: clean review pin 3cf354b; after: clean remediation commit e1c5c55 with focused and full checks passing	Complete

Verification matrix

Surface	Command	Exit code	Outcome
Source/cache preflight	git status --short --branch; opensrc path ...	0	Clean source; Pi 0.84.4 and 0.85.0 source available locally.
Focused cwd reproduction	inline Node harness against Pi 0.84.4	0 (asserted buggy outcome)	Both hidden-worktree requests observed the primary checkout; a missing requested cwd still executed a sentinel command.
Focused cwd regression	bun run --filter '@jbcode/pi-bash-cwd' test	0	Four tests pass: explicit absolute hidden-worktree cwd, relative nested-package cwd, omitted cwd/session environment, configured shell path and command prefix, schema compatibility, missing cwd sentinel, and missing context.
Package contract	bun run test:packages; bun pm pack --destination /tmp --ignore-scripts --quiet	0	Workspace inventory and package contents pass; package tarball created.
Typecheck	bun run typecheck	0	Repository TypeScript check passes.
Full tests	bun run test	0	The complete post-remediation repository test chain passed in background task bg_jdbm_mtng8zhg_2; Node reported 306/306 in the consolidated suite and Vitest reported 22/22 file-search tests.
Fresh-process integration	focused test's delegated real Bash subprocesses	0	Commands execute through Pi 0.84.4's built-in Bash definition with session metadata preserved.

Review

• Base and product HEAD: 7e7cfdb5cb0e1a1218b9a2c8250267d5099637fc and e1c5c55c151fc167eadf56531658482c437b1e61
• Clean status and tree hash: clean; product tree 496022b109fd53b728dc898bf470f87c00129a11
• Commit list: e1c5c55, 3cf354b, 328faa0, 3d68f7c, bda414a, f61f197, 070ba3d, 9d68d5f, 5f853dc
• Exact diff command: git diff --binary --full-index --find-renames 7e7cfdb5cb0e1a1218b9a2c8250267d5099637fc...e1c5c55c151fc167eadf56531658482c437b1e61 --
• SHA-256: b2471221a44d2e507789fad70152059ed42e76807c6af32f1151b95bb498614c
• Mutator identities: parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87
• Standards reviewer identity, digest confirmation, and verdict: cycle 1 bash-cwd-standards, scout child session 01a06e2f-665e-7acc-a2cd-98f976a13b43, digest confirmed, FAIL. Cycle 2's first identity failed with a provider WebSocket error and issued no verdict. Replacement bash-cwd-standards-cycle-2-retry, scout child session 01a06e48-b629-7ad2-bd65-445ad6b8d2ea, independently regenerated the digest and returned PASS with no findings.
• Specification reviewer identity, digest confirmation, and verdict: cycle 1 bash-cwd-specification, scout child session 01a06e2f-b262-77f1-9aef-d5c964cb33b6, subagent 8ae886b2, digest confirmed, FAIL. Cycle 2 bash-cwd-specification-cycle-2 independently confirmed the digest and returned PASS with no findings.
• Findings and remediation cycles: Pi 0.85.0 includes a separate upstream ctx.cwd correction but its public package imports undeclared @earendil-works/pi-server, causing ERR_MODULE_NOT_FOUND; the user selected a repository-owned override instead. During implementation, a direct live call with an extra cwd field still printed the primary checkout, proving Pi's schema/executor silently ignore the requested per-call directory and the first local design addressed the wrong seam. Review cycle 1 accepted three findings: preserve configured shellPath and shellCommandPrefix when recreating Pi's built-in definition; make retirement contingent on equivalent validated per-call cwd; and label npm installation as post-publication. The parent implementer loaded trusted Pi settings at execution, added a realistic custom-shell/prefix regression, and corrected package guidance.
• Before/after reviewer Git evidence: cycle 1 reviewers reported clean feature/honor-bash-worktree-cwd state, product HEAD 328faa0, product tree 6b858045b91298c91f55aedd848c3a02432edafb, and the complete changed-path set before and after their read-only reviews. Cycle 2 passing reviewers reported clean current review-pin HEAD 42dd6ef, product HEAD e1c5c55, product tree 496022b109fd53b728dc898bf470f87c00129a11, matching digest, and unchanged paths/status before and after review.

Integration and rollback

• Synchronization and re-verification: after remediation, fetched origin/main; it remained at the base commit and git rebase origin/main was a no-op, so the verified remediated product tree did not change.
• Fast-forward result: pending
• Product and closure commits: pending
• Reachability and cleanup: pending
• Rollback strategy: before integration, delete only the isolated feature branch/worktree after proof and approval if abandoned; after integration, revert the focused dependency/test/docs product commit.

Checkpoints and blockers

• Last committed valid checkpoint: fresh review pin 42dd6ef
• Blockers: none.
• Exact next safe action: commit the review approvals, run the pre-integration Git gate, and fast-forward clean local main.