# Bash worktree cwd workflow record

## Status

- Status: active
- Current phase: 7. Fresh independent review
- Next safe action: obtain fresh standards and specification review of the remediated pinned diff.

## 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

- [x] `@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.
- [x] Absolute and relative `cwd` values resolve from the live session `ctx.cwd`; omitted `cwd` retains the session directory.
- [x] The requested directory is validated before delegating command execution.
- [x] A regression test executes `pwd` from both a disposable hidden worktree root and a nested workspace package directory and observes the requested directory.
- [x] A missing requested working directory fails before the shell command can create a sentinel side effect.
- [x] Package inventory, README guidance, and the upstream Pi 0.85.0 packaging blocker TODO are synchronized.
- [x] Existing repository typecheck and test suites pass.
- [x] 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; fresh cycle 2 pending.
- 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; fresh cycle 2 pending.
- 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: both 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; current review-pin HEAD remained `3cf354b`.

## 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: remediation commit `e1c5c55`
- Blockers: fresh standards and specification review verdicts are pending.
- Exact next safe action: commit this fresh review pin and launch two new read-only reviewer identities against the recorded digest.