pi-goals/handover.md

# Visible supervisor handover

## Objective

Replace pi-goals' nested pi-subagents worker with two visible Pi sessions:

1. The main session plans with the user, then becomes the implementation worker.
2. On Ready, pi-goals explicitly forks the planning session into a Herdr pane.
3. Only the fork is compacted. It becomes the stronger read-only supervisor.
4. pi-supervise and pi-intercom connect the supervisor to the worker.
5. The worker starts only after the real pi-supervise `pair`/`paired` acknowledgment.
6. The supervisor retains the plan, compact planning context, and concise worker views. It can steer the worker and approve a completed goal.
7. The supervisor compacts near 100k tokens.

Keep this minimal. Reuse pi-supervise's intercom protocol instead of building a second orchestration layer.

## User preferences

- The primary session must do the implementation. Other agents may test or review it, but must not own core development.
- Avoid relaying implementation decisions through multiple agents.
- Herdr should open the supervisor automatically and let the user switch to it.
- Persist configurable models for three stages:
  - planning: strongest model, for example Fable 5.1 or Astra;
  - supervision: for example Sol or Opus;
  - implementation: for example Terra, Sonnet, Kimi K3, DeepSeek Pro, or GLM 5.3.
- Validate model IDs through Pi. Do not hard-code a model list.
- Switch the main session to the planning model when planning starts and to the worker model only after pairing succeeds. Launch the fork with the supervisor model.

## Repository state

pi-goals branch: `experiment/subagent-supervisor`

Committed work:

- `d56fc55` — replace nested workers with a visible supervisor session
- `e299e84` — run supervisor bootstrap through the pane shell
- `c5782ee` — initial pairing handshake, evidence checks, Herdr parsing, and worker intercom ID
- `7eb8b1f` — treat stale pane close as successful cleanup
- `1dc6146` — allow `PI_GOALS_SUPERVISE_EXTENSION` for local development

pi-supervise committed dependency:

- `4e3cd1c` — acknowledged programmatic supervisor pairing API; package version 0.0.4

Uncommitted pi-goals files:

- `src/intercom.ts`
- `src/supervise.ts`
- `test/intercom.test.ts` (new)

Uncommitted pi-supervise file:

- `src/index.ts`

Inspect these diffs before editing. They are a partial design-B refactor and have not passed the real workflow.

## Why design B was selected

Primary-source review found that pi-supervise already sends `pair` and receives the worker's `paired` acknowledgment. The custom `pi-goals/visible-supervisor/v1` intercom namespace duplicated that acknowledgment and introduced another registration and connection race.

Selected design:

- pi-supervise exposes the worker's actual broker ID through a local extension API;
- pi-supervise emits or resolves a worker-local event only after the real `paired` acknowledgment;
- pi-goals passes that broker ID to the supervisor;
- pi-goals waits for that worker-local paired acknowledgment before setting `phase: working` or sending the worker kickoff;
- delete `src/intercom.ts` and custom supervisor-ready messages if the partial diff has not already completed that deletion;
- support either extension load order by using pi-intercom/pi-supervise registry-ready events idempotently.

Do not use pi-intercom `project-agent.ts` as another lifecycle. It opens a generic Pi pane and polls broker presence but does not supply the required fork, extensions, model, or pairing semantics.

## Observed tests and failures

Unit validation before the unfinished design-B refactor:

- pi-goals: 26 tests passed, typecheck passed, lint passed, package dry-run passed, RPC test passed.
- pi-supervise: 97 tests passed and package dry-run passed.

Real Herdr observations:

1. The initial smoke loaded pi-supervise directly from source and did not exercise pi-goals' actual Ready command.
2. A later actual `/goals` → Ready run failed before pane creation because pi-goals emitted `intercom:extension-register` before pi-intercom installed its listener.
3. A local uncommitted registry-ready re-registration fix moved the real path farther: Ready created supervisor pane `w8:p1F` through `supervisorCommand`.
4. That run then timed out waiting for the duplicate custom `supervisor-ready` message. This led to design B.
5. The supervisor exited before its transcript was preserved. Do not infer that pi-supervise pairing succeeded.

The real end-to-end workflow has not passed.

## Next work

1. Read the uncommitted diffs in both repositories and finish or simplify design B.
2. Add focused tests:
   - pi-supervise local API works whether pi-goals loads before or after pi-supervise;
   - no `phase: working` or kickoff before actual `paired`;
   - duplicate `paired` is idempotent.
3. Run the actual pi-goals path, not a substitute command:
   - start worker with pi-goals and pi-intercom;
   - enter `/goals`, draft a plan, and select Ready;
   - use `PI_GOALS_SUPERVISE_EXTENSION=/home/code/.pi/agent/git/github.com/wassname/pi-supervise/src/index.ts` until 0.0.4 is published;
   - positively observe fork-only compaction, actual pairing acknowledgment, then worker kickoff;
   - preserve supervisor stdout/stderr and session JSONL before cleanup on every failure;
   - observe supervisor monitoring or steering;
   - complete real evidence at a clean commit, approve it, call CompleteGoal, and close the pane.
4. Commit the lifecycle separately once the real path passes.
5. Add the three persisted model settings in a separate commit.
6. Run tests, typecheck, lint, package dry-runs, real RPC tests, and a fresh read-only review.

## Known packaging constraint

`src/herdr.ts` defaults to `npm:@wassname2/pi-supervise@0.0.4`. Version 0.0.4 is not publicly published. Do not publish without explicit editorial approval. Local testing must use `PI_GOALS_SUPERVISE_EXTENSION`.

## Important lifecycle bug discovered in this session

`/goals clear` cleared extension state but left the current model request under the previously injected coordinator system instruction. `/reload` did not remove it. A fresh ordinary Pi session is required for direct implementation. The redesign should avoid leaving a session unable to resume ordinary work after clear.

-- PI[gpt-5.6-sol]