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

Bash worktree cwd workflow record

Status

• Status: active
• Current phase: 5. Implement owned slices
• Next safe action: write the focused regression test against Pi 0.84.4, confirm it fails, then upgrade the aligned Pi packages to 0.85.0.

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, adopt the upstream Pi 0.85.0 cwd correction through the repository dependency set, test workspace-root and nested-package execution in a disposable hidden worktree, update affected documentation, and remove the resolved TODO.
• Out of scope: adding a custom Bash override, changing Bash's public per-call arguments, publishing packages, 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

• The repository resolves a Pi Coding Agent version whose built-in Bash tool uses the execution ctx.cwd instead of the tool factory's original process directory.
• 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.
• Existing repository typecheck and test suites pass.
• The resolved 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) add a focused repository regression harness for dynamic Bash ctx.cwd with hidden-worktree root, nested package, and missing-directory cases; (2) update the aligned @earendil-works/pi-ai, @earendil-works/pi-coding-agent, and @earendil-works/pi-tui catalog versions to 0.85.0 and regenerate bun.lock; (3) run focused tests, typecheck, and the full suite; (4) update README compatibility text and resolve the TODO/workaround references; (5) verify in a fresh Pi 0.85.0 process without changing the currently running global Pi installation.
• Plan approval: approved by the user through ask_user on 04SEP2026 (approve_085).
• UI classification and direction approval: non-UI; no prototype gate applies.
• Risk decisions and scope: the user approved the aligned Pi 0.85.0 repository dependency upgrade. The user selected repository-only scope, so the active global Pi 0.84.4 installation remains unchanged.

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
Dependency, test, and docs implementation	parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87	15 minutes	package.json, bun.lock, focused test, README.md, docs/todos.md, workflow record	Before: clean feature worktree at 5f853dc; after: pending	In progress

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	pending repository test	pending	pending
Typecheck	bun run typecheck	pending	pending
Full tests	bun run test	pending	pending
Fresh-process integration	pending	pending	pending

Review

• Base and product HEAD: pending
• Clean status and tree hash: pending
• Commit list: pending
• Exact diff command: pending
• SHA-256: pending
• Mutator identities: parent Pi session 01a06e08-8d07-76a7-a116-d7e3baf55b87
• Standards reviewer identity, digest confirmation, and verdict: pending
• Specification reviewer identity, digest confirmation, and verdict: pending
• Findings and remediation cycles: none yet
• Before/after reviewer Git evidence: pending

Integration and rollback

• Synchronization and re-verification: fetch/rebase onto latest origin/main, then rerun affected and full verification if the effective tree changes.
• 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: initial record commit 5f853dc
• Blockers: none.
• Exact next safe action: commit the approved gate, then implement the focused regression test before updating dependencies.