@dpeek/codeless 0.1.2 → 0.1.3

package/README.md

@@ -12,8 +12,11 @@ consumer application code. Its tests use independent temporary repositories.
 
 ## Installation
 
-Codeless requires Bun, Git, Herdr, and Pi. The scoped package is configured for
-public npm access. Once published, install it with either package manager:
+Codeless requires Bun, Git, Herdr, and Pi. Planner activation requires Herdr's
+official Pi lifecycle integration; install it with `herdr integration install pi`
+and restart existing Pi processes after updating it. The managed launch and
+session-replacement contract is verified against Herdr 0.8.2 and Pi 0.85.1.
+The scoped package is configured for public npm access. Once published, install it with either package manager:
 
 ```sh
 bun add --global @dpeek/codeless
@@ -91,20 +94,30 @@ The configured prompt directory provides `change.md`, `implement.md`,
 
 Path arguments are JSON-quoted. Each direction is `<directions>/<slug>.md`.
 The project owns prompt contents, approval rules, review criteria, and the
-transition from review to commit. Required prompts and directions must exist;
-the runner does not generate or copy project instructions.
+transition from review to commit. `codeless init` creates missing copies of the
+package's four generic starters, but never replaces existing prompt bytes.
+Review and commit those local prompt edits in the invoking checkout, then bring
+that commit onto the configured integration branch before creating streams.
+Required prompts and directions must exist for stream creation and opening.
 
 The package-owned planner extension activates every planner session. Before its
-first project prompt, it requires the exact `<slug>-planner` Pi name, establishes
-and verifies the `<slug>_planner` Herdr identity, and confirms `approve_stream_change`,
+first project prompt, it requires the exact `<slug>-planner` Pi name and verifies
+the `<slug>_planner` Herdr identity, managed interactive readiness, foreground
+worktree, and matching native session reference from Herdr's Pi lifecycle
+integration. It confirms `approve_stream_change`,
 `dispatch_stream_implementer`, `rework_stream_implementer`, `finish_stream_implementer`, and `next_stream_change` are active. Missing or
 incompatible activation, identity mismatch, or inactive tools stops before
-`/change`; global Pi extension installation is unnecessary.
+`/change`. During session replacement, activation allows a brief bounded wait for
+an otherwise-valid Herdr identity to publish the current native Pi reference;
+it never waits on a wrong name, process, lifecycle source, or worktree. Global
+installation of Codeless's extension is unnecessary.
 The approval tool has no arguments. Its extension derives the active
 `<slug>-planner` Pi session and passes it to the backing CLI, which requires it
-to match the worktree and branch. The CLI validates the clean current-integration
-baseline and proposal, exclusively creates the next monotonic `changes/NNN.md`,
-and records one hash-backed journal approval. Exact retries reconcile a missing
+to match the clean stream worktree and branch. That stream commit is the
+proposal's base; approval does not compare it with a concurrently advancing
+integration branch. The CLI validates the proposal, exclusively creates the next
+monotonic `changes/NNN.md`, and records one hash-backed journal approval. Landing
+later owns locked synchronization and any required rebase onto integration. Exact retries reconcile a missing
 file or journal step; conflicting state stops. Approval returns the numbered path
 but does not dispatch it. Dispatch uses the package executable, inherits the
 planner's worktree, and queues review only on success. Pi loads the extension
@@ -121,7 +134,7 @@ sending `/change` after resources reload. The previous conversation is not copie
 journal and project files carry context.
 
 This uses Pi's `newSession({ setup, withSession })` command API, verified with
-Pi 0.84.3. Only the replacement context activates the selection and sends the
+Pi 0.85.1. Only the replacement context activates the selection and sends the
 new prompt. Configuration changes take effect at the next role-session boundary,
 not during an active planner or implementer. Review and remediation therefore
 continue with their existing session's selection. Duplicate requests
@@ -157,8 +170,15 @@ planners or worktree shells are running.
   metrics/<slug>/NNN.json # dispatch/landing times and deduplicated implementer attempts
 ```
 
-Run `codeless init` once after configuring a project. It creates the shared state
-layout and the dedicated integration worktree at
+Run `codeless init` once after configuring a project. It creates missing generic
+`change.md`, `implement.md`, `review.md`, and `commit.md` starters in the
+configured in-project prompt directory, reporting each as created or preserved.
+Existing prompt files are never replaced; review and commit generated files from
+the editable invoking checkout, then bring that commit onto the configured
+integration branch before creating streams. Init refuses to generate missing
+prompts when invoked from the dedicated integration checkout.
+
+It also creates the shared state layout and dedicated integration worktree at
 `<workspace>/worktree/<integration-branch>` without requiring Herdr. For the
 default workspace it adds only `/.codeless/state/` to the primary checkout's
 `.gitignore`; an absolute workspace override does not modify repository ignores.
@@ -172,14 +192,14 @@ inspect its targets before using it.
 
 ## Commands
 
-Run creation, opening, and planner launch from a Herdr-managed shell. Landing
-needs no Herdr session.
+Run creation and opening from a Herdr-managed operator shell outside the target
+planner/implementer panes. Herdr requires an available interactive shell in the
+target pane before it can start Pi. Landing needs no Herdr session.
 
 ```sh
 codeless init
 codeless create <slug>
 codeless open <slug>
-codeless planner <slug>
 codeless approve <planner-session>
 codeless dispatch <numbered-change-file>
 codeless rework <numbered-change-file> <feedback>
@@ -190,15 +210,27 @@ codeless metrics
 ```
 
 Slugs are lowercase kebab-case, at most 24 characters. `init` validates the
-existing configuration and integration branch, reports the branch, primary
-checkout, workspace, and integration worktree, then creates only the shared
-state directories and canonical integration worktree when absent. All other
+existing configuration and integration branch, validates all configured prompt
+destinations before mutation, reports created or preserved starters plus the
+branch, primary checkout, workspace, and integration worktree, then creates the
+shared state directories and canonical integration worktree when absent. All other
 commands validate their prerequisites and never bootstrap this setup. `create` starts
 `stream/<slug>` from the integration branch and creates its local documents;
-it refuses existing streams. `open` resumes a stream. Both run the configured
-install command, then validate and open a planner beside an idle shell. `planner`
-starts Pi in an existing stream's lone shell after the same role preflight. Its
-activation establishes the same identity as creation and reopening.
+it refuses existing streams. `open` reuses the existing stream workspace and
+one- or two-pane layout. It focuses an existing managed planner without installing
+dependencies, sending another prompt, or replacing its conversation. To restart,
+exit Pi deliberately, leave both stream panes at their shell prompts in the
+stream worktree, then run `codeless open <slug>` from another Herdr shell.
+
+When a planner must be started, creation/opening validates the available shells,
+runs the configured install command and role preflight, adds a right-hand shell
+only when absent, and uses `herdr agent start` for named, readiness-checked Pi
+startup. It verifies the result before sending activation. An occupied or
+mismatched pane, unmanaged agent, ambiguous layout, or failed startup stops;
+Codeless never takes over an existing agent. Pi's display name is separate from
+Herdr's managed agent name. Activation verifies names and native session binding;
+it never renames an unmanaged process. There is no direct `planner` command.
+
 Dispatch validates the implementer selection before touching the planner's
 right-hand pane, starts a fresh ephemeral implementer with Codeless's reporting
 extension and its explicit Pi extension flag, and waits for completion. Rework verifies
@@ -262,8 +294,8 @@ control Pi itself. Preparation can be repeated safely after inspecting a failure
 
 If validation or session replacement fails, the planner stops for operator
 attention. Landing is already complete, and any preparation fast-forward remains
-applied. There is no background retry; restarting the planner recovers from the
-journal and Git state.
+applied. There is no background retry; exit Pi and reopen the stream from another
+Herdr shell to recover from the journal and Git state.
 
 ## Package development
 

package/extension/planner.js

@@ -1,8 +1,11 @@
 import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { validAttempt } from "../src/attempt.ts";
 
 const codeless = fileURLToPath(new URL("../bin/codeless", import.meta.url));
 const thinkingLevels = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const nativeSessionAttempts = 20;
+const nativeSessionRetryDelayMs = 50;
 const requiredTools = [
   "approve_stream_change",
   "dispatch_stream_implementer",
@@ -93,24 +96,47 @@ export default function plannerExtension(pi) {
           throw new Error("Herdr returned an invalid planner identity response");
         }
       };
-      let agent = await plannerIdentity();
-      if (agent?.name === "pi") {
-        const renamed = await pi.exec("herdr", ["agent", "rename", pane, expectedPlanner], {
-          timeout: 30_000,
-        });
-        if (renamed.code !== 0) {
+      const attempts = activation ? nativeSessionAttempts : 1;
+      for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const agent = await plannerIdentity();
+        if (agent?.name !== expectedPlanner) {
           throw new Error(
-            renamed.stderr.trim() ||
-              renamed.stdout.trim() ||
-              "Codeless could not establish Herdr planner identity",
+            `Codeless planner identity is ${agent?.name ?? "missing"}, expected ${expectedPlanner}; exit this agent and run codeless open ${match[1]} from another Herdr shell`,
           );
         }
-        agent = await plannerIdentity();
-      }
-      if (agent?.name !== expectedPlanner) {
-        throw new Error(
-          `Codeless planner identity is ${agent?.name ?? "missing"}, expected ${expectedPlanner}`,
-        );
+        if (agent.agent !== "pi" || agent.interactive_ready !== true) {
+          throw new Error("Codeless requires a Herdr-managed Pi planner started by codeless open");
+        }
+        if (
+          typeof agent.foreground_cwd !== "string" ||
+          resolve(agent.foreground_cwd) !== resolve(ctx.cwd)
+        ) {
+          throw new Error("Codeless planner worktree does not match Herdr's foreground cwd");
+        }
+        const session = agent.agent_session;
+        const expectedSession =
+          session?.kind === "path"
+            ? ctx.sessionManager.getSessionFile()
+            : session?.kind === "id"
+              ? ctx.sessionManager.getSessionId()
+              : undefined;
+        if (
+          agent.screen_detection_skipped !== true ||
+          session?.source !== "herdr:pi" ||
+          session.agent !== "pi" ||
+          !expectedSession
+        ) {
+          throw new Error(
+            "Codeless planner native session does not match Herdr's Pi lifecycle integration",
+          );
+        }
+        if (session.value === expectedSession) break;
+        if (attempt === attempts - 1) {
+          throw new Error(
+            "Codeless planner native session does not match Herdr's Pi lifecycle integration",
+          );
+        }
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, nativeSessionRetryDelayMs));
       }
       const activeTools = ctx.getSystemPromptOptions().selectedTools ?? [];
       const missing = requiredTools.filter((tool) => !activeTools.includes(tool));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpeek/codeless",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "An attended planner and implementer workflow for parallel capability development",
   "homepage": "https://github.com/dpeek/codeless#readme",
   "bugs": {
@@ -17,6 +17,7 @@
   "files": [
     "bin",
     "extension",
+    "prompts",
     "src",
     "README.md",
     "spec"

package/prompts/change.md

@@ -0,0 +1,40 @@
+---
+description: Propose and coordinate the next small change for a stream
+argument-hint: "<stream-directory> <direction-file>"
+---
+
+You are the planner for the stream at `$1`. The current working directory is the stream's repository worktree.
+
+Read the repository guidance, `.codeless/config.json`, `$1/planner.md`, every numbered Markdown file in `$1/changes/`, `$2`, its related contracts, and the current implementation relevant to the stream. Resolve the integration branch from that configuration.
+
+Before proposing, inspect the branch, recent commits, and worktree. If changes are not explained as an active approved change in `planner.md`, stop and show the operator the evidence. Never discard work automatically.
+
+If the latest numbered change is approved but uncommitted, resume it. If it is committed but unlanded on the configured integration branch, resume review or landing. Otherwise require a clean worktree with no commits outside the configured integration branch, fast-forward to that branch, and reread the direction and affected contracts. Stop on divergence. Once planning begins, keep that stream commit as the proposal's base; do not resynchronize merely because integration advances while the proposal awaits approval. Locked landing owns the later rebase.
+
+Propose exactly one small, complete change and write it to `$1/change.md`:
+
+```markdown
+# <short outcome>
+
+## Why
+
+## Change
+
+## Acceptance
+
+## Decisions
+```
+
+Under `Decisions`, record only choices that matter now; write `None` when there are none.
+
+Present the proposal and wait for the operator:
+
+- `go`: call `approve_stream_change` exactly once. It validates and promotes the proposal, records one approval, and returns its number, title, and absolute numbered change path. After it succeeds, call `dispatch_stream_implementer` exactly once with that returned change path.
+- `no`: append the rejected proposal and reason to `planner.md`; do not allocate a numbered change.
+- other feedback: revise `change.md`, recheck the relevant state, and present it again.
+
+Approval is separate from dispatch. Do not edit approval state by hand or reproduce the dispatch tool's worktree, pane, or agent operations. If dispatch returns an error, stop and show the operator the exact error; do not retry automatically.
+
+After the implementer settles, follow the queued `/review <absolute-numbered-change-path>` instruction. Do not finish after merely reporting that implementation settled. Keep this implementer alive for every remediation round belonging to the same numbered change.
+
+The implementation updates code, focused tests, owning contracts, and the direction; remove satisfied todo intentions. If no worthwhile work remains, say so.

package/prompts/commit.md

@@ -0,0 +1,37 @@
+---
+description: Commit one reviewed stream change
+argument-hint: "<numbered-change-file>"
+---
+
+Commit the reviewed implementation of `$1` on the current stream branch.
+
+Before committing or landing:
+
+- confirm `planner.md` records review approval for this change;
+- inspect the complete diff for unrelated edits;
+- confirm every acceptance criterion is met;
+- run the relevant checks if their passing result is not current;
+- determine whether this reviewed change already has its one commit because a previous landing attempt stopped.
+
+If the change is not committed, create exactly one commit. Use an imperative subject that describes the resulting behavior. Add a short body only for a non-obvious design decision. If the reviewed change already has its one unlanded commit, do not create another.
+
+Read `.codeless/config.json` to resolve the configured integration branch. Derive `<slug>` from the numbered change path and land it with:
+
+```sh
+codeless land <slug>
+```
+
+Replace the placeholder with the literal stream slug and do not include angle brackets. This command owns the shared integration lock, rebases the one stream commit when the configured integration branch advanced, runs the configured checks, and fast-forwards the dedicated integration checkout. It does not modify other branches or checkouts.
+
+If landing succeeds, append the full commit hash and subject plus a `landed on <configured-integration-branch>` note to the stream's `planner.md`. Include any decisions the next planner needs before resetting the session.
+
+Then call `next_stream_change` exactly once with `changePath` set to the absolute path of `$1` and `landedCommit` set to that full hash. Finish this turn after requesting the handoff. The tool validates the completed landing, fast-forwards the stream to the current configured integration branch, and starts a fresh planner session with the project's `/change` prompt. Do not propose the next change in this session or send `/new` through shell keystrokes.
+
+The next planner proposes one change and waits for the operator's `go`; this handoff does not approve further implementation. If no worthwhile work remains, it reports that and stops. If handoff validation fails or the reset is cancelled, stop and report the state; do not retry automatically. Landing remains complete even if the handoff fails.
+
+There are two expected landing stops:
+
+- If another stream owns the integration slot, leave this stream committed where it is, report the owner, and wait. Do not poll, queue, or retry automatically.
+- If this stream owns the slot and the rebase conflicts, keep the slot. Resolve the conflicts in this worktree so both the current configured integration branch and the approved change are preserved, stage the resolutions, and continue the rebase with `GIT_EDITOR=true git rebase --continue`. Repeat until the rebase completes, run the relevant checks, then run `codeless land <slug>` again to finish. The slot prevents another automated landing from moving the integration branch while you resolve it.
+
+For any other failure while this stream owns the slot, report the exact state and wait for the operator. The slot remains held for deliberate recovery; never remove the workspace's landing lock automatically or on guesswork.

package/prompts/implement.md

@@ -0,0 +1,17 @@
+---
+description: Implement one approved stream change
+argument-hint: "<numbered-change-file>"
+---
+
+You are the implementer. Implement only the approved change in `$1` in the current worktree.
+
+Read the numbered change, repository guidance, and the smallest relevant part of the codebase. Preserve unrelated work.
+
+- Do not edit the planner journal, current proposal, or numbered changes beside `$1`.
+- Do not commit, rebase, merge, switch branches, or reset files.
+- Update the owning contracts and todo with the implementation.
+- Add or update focused tests for changed behavior.
+- Run the smallest useful checks.
+- If the change cannot be completed safely, stop and explain the blocker with evidence.
+
+When finished, report what changed, checks run and their results, and assumptions or remaining concerns.

package/prompts/review.md

@@ -0,0 +1,20 @@
+---
+description: Review the worktree against one approved stream change
+argument-hint: "<numbered-change-file>"
+---
+
+You are the planner reviewing the implementation of `$1`.
+
+Read the approved change and repository guidance. Inspect the complete worktree diff and relevant surrounding code. Review for correctness and regressions, unmet acceptance criteria, missing or weak tests, accidental scope growth, and consistency with the repository's domain model and style.
+
+Run focused checks when the implementation report is insufficient evidence.
+
+If remediation is required, call `rework_stream_implementer` once with `$1` as `changePath` and a concise actionable feedback list. The tool reuses the verified idle implementer, waits for its one feedback turn, returns its rework attempt, and queues review again. Do not reproduce agent operations or retry automatically.
+
+If operator judgment is required, stop and ask one concrete question. If the change is ready:
+
+1. append a compact approval and verification summary to the stream's `planner.md`;
+2. call `finish_stream_implementer` once with `$1` as `changePath`; it gracefully exits the verified implementer and confirms its pane returned to the stream shell;
+3. only after that tool succeeds, read `.codeless/config.json`, resolve its `prompts` directory, and immediately follow that directory's `commit.md` instructions for `$1`.
+
+Do not finish the implementer before approval because remediation for this numbered change retains its context. If the finish tool fails, stop and report its error.

package/spec/workflow.md

@@ -1,16 +1,19 @@
 # Codeless workflow
 
-Codeless is an attended workflow for delivering independent capability changes
-through a project's integration branch. This contract owns the implemented
-workflow; the [project guide](../README.md) explains installation, operation,
-and reusable execution mechanics. Missing workflow behavior belongs in
-[the workflow todo](../todo/workflow.md).
+Codeless is an attended workflow for delivering independent capability changes through a
+project's integration branch. This contract owns the implemented workflow; the [project
+guide](../README.md) explains installation, operation, and reusable execution mechanics.
+Missing workflow behavior belongs in [the workflow todo](../todo/workflow.md).
 
-## Stream and change lifecycle
+## Ownership and lifecycle
 
-A stream has one lowercase kebab-case slug, one `stream/<slug>` branch and
-worktree, one planner, one implementer pane, and at most one approved change in
-progress. Work inside a stream is sequential:
+Codeless owns reusable execution mechanics and shared local state. Projects own
+directions, prompt contents, model choices, and approval/review policy. Pi and Herdr own
+their runtime APIs and process behavior.
+
+A stream has one lowercase kebab-case slug, one `stream/<slug>` branch and worktree, one
+planner, one implementer pane, and at most one approved change in progress. Work inside
+a stream is sequential:
 
 1. create or reopen the stream from the configured integration branch;
 2. propose one small change and wait for operator approval;
@@ -21,22 +24,42 @@ progress. Work inside a stream is sequential:
    slot; and
 6. replace the planner session before proposing another change.
 
-Automated landing updates only the configured integration branch's dedicated
-clean checkout. Other branches and checkouts are neither stream sources nor
-landing targets. Codeless does not push.
+Automated landing updates only the configured integration branch's dedicated clean
+checkout. Other branches and checkouts are neither stream sources nor landing targets.
+Codeless does not push.
+
+Each project supplies `.codeless/config.json`, a direction at `<directions>/<slug>.md`, and
+`change`, `implement`, `review`, and `commit` prompt templates. Creation refuses a
+missing direction or prompt and an existing stream. Opening requires the existing
+branch, worktree, journal, proposal file, direction, and prompts. Both install
+dependencies before starting a new planner. Reopening a running managed planner
+only focuses its workspace and preserves its conversation.
+
+## Command and tool boundaries
 
-Each project supplies `.codeless/config.json`, a direction at
-`todo/<slug>.md`, and `change`, `implement`, `review`, and `commit` prompt
-templates. Creation refuses a missing direction or prompt and an existing
-stream. Opening requires the existing branch, worktree, journal, proposal file,
-direction, and prompts. Both install dependencies before starting the planner.
+The executable currently exposes both operator commands and subprocess entrypoints used
+by planner tools:
+
+| Surface                                           | Responsibility                                                                |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `init`, `create`, `open`, `metrics`               | Operator setup, session management, and observation                           |
+| `approve`, `dispatch`, `rework`, `finish`, `next` | Backing commands for the corresponding planner tools                          |
+| `land`                                            | Commit integration, invoked by the project prompt or operator during recovery |
+| `/change`, `/implement`, `/review`, `/commit`     | Project-owned prompt templates                                                |
+| `/streams-activate`, `/streams-next`              | Package-owned planner activation and session replacement                      |
+| `/codeless-rework`, `/codeless-finish`            | Package-owned commands delivered to the existing implementer                  |
+
+The Pi commands bridge session/process operations. In particular, `next_stream_change`
+queues a command so session replacement occurs after the current turn settles. Surface
+reductions and additional tools belong in the workflow todo; all backing CLI commands
+remain callable today.
 
 ## Shared local state
 
-Codeless keeps workflow state outside tracked project documents in a shared
-workspace selected by the local Git `codeless.workspaceRoot` setting or, by
-default, at `.codeless/state/` in the primary checkout. The default directory is
-Git-ignored, and every linked worktree resolves the same primary-checkout state:
+Codeless keeps workflow state outside tracked project documents in a shared workspace
+selected by the local Git `codeless.workspaceRoot` setting or, by default, at
+`.codeless/state/` in the primary checkout. The default directory is Git-ignored, and
+every linked worktree resolves the same primary-checkout state:
 
 ```text
 <primary-checkout>/.codeless/state/
@@ -49,183 +72,212 @@ Git-ignored, and every linked worktree resolves the same primary-checkout state:
   metrics/<slug>/NNN.json
 ```
 
-`codeless init` is the explicit, idempotent bootstrap for a configured project.
-It requires the configured integration branch to exist and creates the shared
-state directories plus that branch's worktree only at
+`codeless init` is the explicit, idempotent bootstrap for a configured project. It
+requires the configured integration branch and creates missing copies of the four
+package-owned generic prompt starters in the invoking checkout's configured in-project
+prompt directory. It validates every template and destination before mutation, reports
+each absolute path as created or preserved, and never replaces an existing prompt file.
+A non-directory ancestor or non-file prompt collision stops without prompt, state, ignore,
+or worktree mutation. Missing prompts are not generated when init is invoked from the
+dedicated integration checkout; the operator must initialize from an editable checkout.
+
+Init creates the shared state directories plus that branch's worktree only at
 `<workspace>/worktree/<integration-branch>`. It reuses only the exact registered
-canonical checkout. An occupied target, a branch registered elsewhere, invalid
-checkout, or ambiguous Git registration stops unchanged; init never switches
-branches, moves worktrees, or repairs conflicts. With the default workspace,
-it accepts a repository ignore rule only when it ignores the state path without
-covering configuration or configured prompts, otherwise appending the narrow
-`/.codeless/state/` rule. An absolute workspace never changes repository
-ignores. No other command bootstraps this layout.
-
-`planner.md` owns decisions, approvals, review outcomes, landing history, and
-the context needed by a fresh planner. `change.md` is the editable current
-proposal. `changes/NNN.md` is the immutable-by-policy approved input to one
-implementation loop. These documents are local workflow state, not product
-contracts, and are never copied into `spec/`.
+canonical checkout. An occupied target, a branch registered elsewhere, invalid checkout,
+or ambiguous Git registration stops unchanged; init never switches branches, moves
+worktrees, or repairs conflicts. With the default workspace, it accepts a repository
+ignore rule only when it ignores the state path without covering configuration or
+configured prompts, otherwise appending the narrow `/.codeless/state/` rule. An absolute
+workspace never changes repository ignores. No other command bootstraps this layout.
+
+`planner.md` owns decisions, approvals, review outcomes, landing history, and the
+context needed by a fresh planner. `change.md` is the editable current proposal.
+`changes/NNN.md` is the immutable-by-policy approved input to one implementation loop.
+These documents are local workflow state, not product contracts, and are never copied
+into `spec/`.
 
 After operator `go`, the argument-free planner-only `approve_stream_change` tool
-promotes the current proposal before any dispatch. It derives the active planner
-session and passes it to the backing CLI, which requires its `<slug>-planner`
-identity to match the clean `stream/<slug>` worktree and branch exactly at the
-current integration branch. The proposal needs one usable H1 title plus the `Why`, `Change`,
-`Acceptance`, and `Decisions` headings; titles must be representable by the
-canonical record. The CLI writes `changes/NNN.md` exclusively, where `NNN` is
-the successor of the greatest existing three-digit number (and stops after
-`999`), then appends a canonical journal approval containing the file, title,
-and proposal hash. Repeated calls reconcile that exact file and entry, completing
-one missing step without another number; conflicting or ambiguous partial state
-stops unchanged. Rejection and ordinary feedback allocate nothing. Dispatch
-remains a separate explicit tool call using the returned absolute path.
+promotes the current proposal before any dispatch. It derives the active planner session
+and passes it to the backing CLI, which requires its `<slug>-planner` identity to match
+the clean `stream/<slug>` worktree and branch. The stream commit established for
+planning is the proposal's base; approval does not compare it with the moving
+integration branch. Landing alone acquires the integration lock and rebases that
+stream change when integration has advanced. The proposal needs one usable H1 title plus
+the `Why`, `Change`, `Acceptance`, and
+`Decisions` headings in that order; titles must be representable by the canonical
+record. The CLI writes `changes/NNN.md` exclusively, where `NNN` is the successor of the
+greatest existing three-digit number (and stops after `999`), then appends a canonical
+journal approval containing the file, title, and proposal hash. Repeated calls reconcile
+that exact file and entry, completing one missing step without another number;
+conflicting or ambiguous partial state stops unchanged. Rejection and ordinary feedback
+allocate nothing. Dispatch remains a separate explicit tool call using the returned
+absolute path.
 
 ## Role sessions and configuration
 
 Project configuration selects an exact Pi provider, model, and thinking level
 independently for planner and implementer roles.
 
-Before starting either role, Codeless uses Pi's machine-readable APIs to require
-the configured model, authentication, supported thinking level, and effective
-selection. It fails before agent work rather than accepting a fallback model or
-clamped thinking level. The validated selection is displayed and passed to the
-role process.
-
-Configuration changes take effect only at a new role-session boundary. An
-active review or remediation keeps its implementer setting. A successful
-post-landing handoff rereads and validates planner configuration from the
-fast-forwarded stream worktree before the replacement session receives its
-first project prompt.
-
-Every planner launch—creation, reopening, direct `planner` restart, and
-post-landing replacement—uses the package-owned extension as its activation
-boundary. Before its first project prompt, activation requires the exact
-`<slug>-planner` Pi session name, establishes and verifies Herdr reports
-`<slug-with-hyphens-replaced>_planner`, and verifies
-`approve_stream_change`, `dispatch_stream_implementer`, `rework_stream_implementer`,
-`finish_stream_implementer`, and `next_stream_change` are active. Missing or incompatible activation, identity
-mismatch, or an incomplete tool set stops visibly before `/change`. A direct
-restart may begin with Herdr's `pi` fallback identity; activation renames and
-rereads only that fallback. Any other identity mismatch stops. Implementers use
-the corresponding `_impl` and `-impl` forms. The package loads its planner
-extension explicitly; global Pi extension installation is not required.
+Before starting either role, Codeless uses Pi's machine-readable APIs to require the
+configured model, authentication, supported thinking level, and effective selection. It
+fails before agent work rather than accepting a fallback model or clamped thinking
+level. The validated selection is displayed and passed to the role process.
+
+Configuration changes take effect only at a new role-session boundary. An active review
+or remediation keeps its implementer setting. A successful post-landing handoff rereads
+and validates planner configuration from the fast-forwarded stream worktree before the
+replacement session receives its first project prompt.
+
+Every new planner process uses `herdr agent start`, which owns its managed name
+and waits for interactive readiness before Codeless sends activation. `open`
+reuses the stream workspace and its root planner pane, adding a right-hand shell
+only when absent. It accepts only a lone planner pane or a planner with one
+right-hand pane. Starting a planner requires both existing panes to be shells in
+the stream worktree; occupied, mismatched, or ambiguous layouts stop unchanged.
+The operator must invoke opening from outside those target panes. Reopening an
+existing managed planner focuses it without installation or another prompt.
+
+The package-owned extension activates creation, reopening, and post-landing
+replacement. Before the first project prompt it requires the exact
+`<slug>-planner` Pi name, `<slug-with-hyphens-replaced>_planner` Herdr name,
+managed interactive readiness, matching foreground worktree, and the current
+native Pi session ID/file reported by Herdr's official Pi lifecycle integration.
+It verifies `approve_stream_change`, `dispatch_stream_implementer`,
+`rework_stream_implementer`, `finish_stream_implementer`, and `next_stream_change`
+are active. During replacement, an otherwise-valid previous native session
+reference receives a brief bounded synchronization wait; a wrong name, process,
+lifecycle source, or worktree fails immediately. Any binding that remains missing
+or incompatible stops visibly before `/change`. Activation never repairs names.
+The direct `planner` command is removed;
+recovery exits Pi deliberately and reopens from another Herdr shell.
+
+Pi session replacement keeps the managed process and Herdr name while changing
+its native conversation reference. Codeless revalidates that new binding before
+prompting the replacement. Implementers use the corresponding `_impl` and
+`-impl` names. Codeless loads its own extension explicitly; Herdr's official Pi
+integration supplies lifecycle and native-session reporting. This boundary was
+verified against Herdr 0.8.2 and Pi 0.85.1.
 
 ## Dispatch and review
 
 The planner-only `dispatch_stream_implementer` tool accepts an absolute approved
-`changes/NNN.md` path. Dispatch verifies the stream branch, clean worktree,
-planner pane, prompts, and implementer selection. It creates or reuses the
-right-hand Herdr pane only when that pane is an available shell or the expected
-idle implementer, starts a fresh ephemeral Pi implementer in the stream
-worktree, submits `/implement`, and waits for at most one hour.
+`changes/NNN.md` path. Dispatch verifies the stream branch, clean worktree, planner
+pane, prompts, and implementer selection. It creates or reuses the right-hand Herdr pane
+only when that pane is an available shell or the expected idle implementer, starts a
+fresh ephemeral Pi implementer in the stream worktree, submits `/implement`, and waits
+for at most one hour.
 
 Successful dispatch loads the package-owned reporting extension while retaining
-`--no-session` and passes its report configuration through that extension's
-explicit Pi string flag, then returns one normalized attempt to the planner tool
-before it queues the expanded `/review` prompt. Attempts have a stable ID and
-capture only stream/change/role, start and settlement timestamps, Pi's actual
-settled provider/model/thinking selection, terminal outcome and final text,
-full-session Pi input/output/cache usage (including tool results, compaction,
-and branch summaries), available Pi model cost estimate with USD currency and
-source, and tool/error counts. Cost is omitted when Pi did not supply valid
-cost totals. They do not retain prompts, source, credentials, thinking, or a
-transcript. The extension writes its narrow report atomically once, then
-remains disarmed for remediation; Codeless atomically deduplicates it inside the
-per-change metric record, rejecting a
-conflicting duplicate ID. Missing, malformed, or unwritable collection warns
-and yields an explicitly incomplete attempt when possible without failing or
-repeating a settled implementation.
-
-The planner inspects the full diff and relevant code, checks the approved
-acceptance criteria, and runs focused checks when the implementation output is
-insufficient. The planner-only `rework_stream_implementer` tool accepts that
-approved path and concise feedback, verifies the expected idle implementer, its
-right-hand pane and worktree, then invokes one package-owned Pi command. That command
-verifies the immutable startup stream/change scope, arms package reporting in the existing
-conversation, and submits one bounded feedback turn. It records
-and returns one `rework` attempt before queueing review again; missing or malformed
-reports warn and yield an incomplete attempt after settlement. Prompt rejection,
-timeout, blocked state, identity/worktree/change mismatch, or ambiguous pane stops
-without a completed attempt or queued review. The separate planner-only
-`finish_stream_implementer` tool first verifies that immutable stream/change scope in the
-same idle implementer, then gracefully exits it and waits for its pane to become the
-stream-worktree shell. Its failure
-stops before commit or landing instructions continue.
-
-Dispatch, remediation, and shutdown do not retry automatically or replace an
-implementer session or its selected model.
+`--no-session` and passes its report configuration through that extension's explicit Pi
+string flag, then returns one normalized attempt to the planner tool before it queues
+the expanded `/review` prompt. Attempts have a stable ID and capture only
+stream/change/role, start and settlement timestamps, Pi's actual settled
+provider/model/thinking selection, terminal outcome and final text, Pi
+input/output/cache usage over the collected attempt (including tool results, compaction,
+and branch summaries), available Pi model cost estimate with USD currency and source,
+and tool/error counts. Cost is omitted when Pi did not supply valid cost totals.
+Collection stores final assistant text and aggregate measurements, not a transcript or
+separate prompt, source, credential, or thinking fields. Final assistant text is not
+redacted. The extension writes its report atomically once, then remains disarmed for
+remediation; Codeless atomically deduplicates it inside the per-change metric record,
+rejecting a conflicting duplicate ID. Missing, malformed, or unwritable collection warns
+and yields an explicitly incomplete attempt when possible without failing or repeating a
+settled implementation.
+
+The planner inspects the full diff and relevant code, checks the approved acceptance
+criteria, and runs focused checks when the implementation output is insufficient. The
+planner-only `rework_stream_implementer` tool accepts that approved path and concise
+feedback, verifies the expected idle implementer, its right-hand pane and worktree, then
+invokes one package-owned Pi command. That command verifies the immutable startup
+stream/change scope, arms package reporting in the existing conversation, and submits
+one bounded feedback turn. It records usage from that remediation turn, excluding
+earlier conversation entries, and returns one `rework` attempt before queueing review
+again; missing or malformed reports warn and yield an incomplete attempt after
+settlement. Prompt rejection, timeout, blocked state, identity/worktree/change mismatch,
+or ambiguous pane stops without a completed attempt or queued review. The separate
+planner-only `finish_stream_implementer` tool first verifies that immutable
+stream/change scope in the same idle implementer, then gracefully exits it and waits for
+its pane to become the stream-worktree shell. Its failure stops before commit or landing
+instructions continue.
+
+Dispatch, remediation, and shutdown do not retry automatically or replace an implementer
+session or its selected model.
 
 ## Commit and landing
 
-A reviewed change produces exactly one commit outside the merge base with the
-configured integration branch. `codeless land <slug>` requires clean stream and integration worktrees,
-then atomically acquires the shared `.land-lock` with its owner and captured
+A reviewed change produces exactly one commit outside the merge base with the configured
+integration branch. `codeless land <slug>` requires clean stream and integration
+worktrees, then atomically acquires the shared `.land-lock` with its owner and captured
 integration commit.
 
-If the integration branch advanced, landing rebases the single stream commit. It then rereads and
-runs the configured project check in the stream worktree, requires checks to
-leave the worktree clean, and fast-forwards the dedicated `main` checkout. Only
+If the integration branch advanced, landing rebases the single stream commit. It then
+rereads and runs the configured project check in the stream worktree, requires checks to
+leave the worktree clean, and fast-forwards the dedicated integration checkout. Only
 successful completion releases the lock.
 
-A lock owned by another stream stops landing without polling. A rebase conflict,
-failed check, or other error after acquisition retains this stream's lock for
-deliberate recovery. Rerunning landing for the same owner is allowed only while
-the recorded integration commit still matches. Codeless never removes a stale or
-ambiguous lock automatically.
+A lock owned by another stream stops landing without polling. A rebase conflict, failed
+check, or other error after acquisition retains this stream's lock for deliberate
+recovery. Rerunning landing for the same owner is allowed only while the recorded
+integration commit still matches. Codeless never removes a stale or ambiguous lock
+automatically.
 
 ## Fresh planner handoff
 
 After landing, the planner records the full landed commit hash and calls the
-planner-only `next_stream_change` tool exactly once. The handoff requires the
-latest numbered change, its full hash in the journal and stream history, no
-unlanded stream commit, a clean worktree, and no unresolved lock owned by this
-stream or by an unknown owner.
-
-Codeless captures the current integration branch, fast-forwards the stream worktree, validates
-the updated direction, prompts, and planner selection, and returns the next
-session name and `/change` prompt. The extension replaces the Pi session in the
-same pane, preserves its name, activates the validated selection and planner
-identity, and only then sends the project prompt. Conversation history is not copied; the journal and
+planner-only `next_stream_change` tool exactly once. The handoff requires the latest
+numbered change, the full landed commit hash in the journal and stream history, no unlanded stream
+commit, a clean worktree, and no unresolved lock owned by this stream or by an unknown
+owner.
+
+Codeless captures the current integration branch, fast-forwards the stream worktree,
+validates the updated direction, prompts, and planner selection, and returns the next
+session name and `/change` prompt. The extension replaces the Pi session in the same
+pane, preserves its name, activates the validated selection and planner identity, and
+only then sends the project prompt. Conversation history is not copied; the journal and
 project files carry durable context.
 
 A cancelled or failed replacement stops for operator attention. Landing remains
-complete, and any successful preparation fast-forward remains applied. There is
-no background retry. The replacement planner still needs a new operator `go`
-before another implementation.
+complete, and any successful preparation fast-forward remains applied. There is no
+background retry. The replacement planner still needs a new operator `go` before another
+implementation.
 
 ## Local workflow metrics
 
-The first dispatch for a stream and numbered change creates one atomic local
-metric record. Every accepted dispatch creates a new attempt ID; re-ingesting an
-attempt ID is atomic and idempotent, while the original dispatch timestamp stays
-unchanged. Successful landing adds its timestamp and commit, or creates a landed
-record with unavailable elapsed time when dispatch collection was unavailable.
-Collection warnings do not change dispatch or landing outcomes.
-
-`codeless metrics` reports every recorded stream and a project total in two
-tables. The elapsed table reports landed and dispatched-but-unlanded change
-counts, measured versus unavailable elapsed coverage, and total and average
-dispatch-to-land wall-clock time. The attempt table aggregates only validated
-canonical attempt records and reports distinct changes with rework, initial and
-rework turns, incomplete collection, exact stored terminal-outcome labels, and
-summed tool errors.
-
-Usage coverage is measured versus unavailable attempts; input, output,
-cache-read, and cache-write totals include only attempts with recorded usage.
-Cost coverage follows the same rule, and totals are grouped by recorded currency
-without conversion. Missing usage or cost is unavailable, never zero. These
-measurements do not establish implementation quality or review success. They
-are prospective local observations, not journal state, an approval source, or a
-recovery mechanism.
+The first dispatch for a stream and numbered change creates one atomic local metric
+record. Every accepted dispatch creates a new attempt ID; re-ingesting an attempt ID is
+atomic and idempotent, while the original dispatch timestamp stays unchanged. Successful
+landing adds its timestamp and commit, or creates a landed record with unavailable
+elapsed time when dispatch collection was unavailable. Collection warnings do not change
+dispatch or landing outcomes.
+
+`codeless metrics` reports every recorded stream and a project total in two tables. The
+elapsed table reports landed and dispatched-but-unlanded change counts, measured versus
+unavailable elapsed coverage, and total and average dispatch-to-land wall-clock time.
+The attempt table aggregates only validated canonical attempt records and reports
+distinct changes with rework, initial and rework turns, incomplete collection, exact
+stored terminal-outcome labels, and summed tool errors.
+
+Usage coverage is measured versus unavailable attempts; input, output, cache-read, and
+cache-write totals include only attempts with recorded usage. Cost coverage follows the
+same rule, and totals are grouped by recorded currency without conversion. Missing usage
+or cost is unavailable, never zero. These measurements do not establish implementation
+quality or review success. They are prospective local observations, not journal state,
+an approval source, or a recovery mechanism.
 
 ## Limits
 
-Codeless is attended and intentionally has no supervisor, project registry,
-queue, automatic landing retry, stale-lock recovery, or unattended approval.
-Planner startup reads every numbered change, and conflict recovery currently
-causes the configured landing check to run twice. Because the default state is
-ignored, `git clean -fdx` can delete it.
+Codeless is attended and intentionally has no supervisor, project registry, queue,
+automatic landing retry, stale-lock recovery, or unattended approval. Planner startup
+reads every numbered change, and conflict recovery currently causes the configured
+landing check to run twice. Because the default state is ignored, `git clean -fdx` can
+delete it.
+
+The single-active-change rule and the requirement to dispatch only approved input still
+partly depend on planner instructions. Approval reconciles records and hashes but does
+not require the previous approved change to be complete before allocating a different
+proposal. Dispatch requires an existing numbered file, but does not validate its
+approval record/hash or require it to be the latest change. These are implementation
+gaps, not additional permissions.
 
 ## References
 

package/src/cli.ts

@@ -25,7 +25,6 @@ const usage = `Usage:
   codeless init
   codeless create <slug>
   codeless open <slug>
-  codeless planner <slug>
   codeless approve <planner-session>
   codeless dispatch <numbered-change-file>
   codeless rework <numbered-change-file> <feedback>
@@ -167,6 +166,37 @@ export async function runCodeless(args: string[]): Promise<void> {
     run("git", ["show-ref", "--verify", `refs/heads/${integrationBranch}`], repository);
     const primary = primaryWorktree();
     const target = canonicalPath(join(workspaceRoot, "worktree", integrationBranch));
+    const promptNames = ["change", "implement", "review", "commit"];
+    const promptDirectory = join(repository, project.prompts);
+    const promptTemplates = join(import.meta.dir, "../prompts");
+    const promptPlan = promptNames.map((name) => {
+      const template = join(promptTemplates, `${name}.md`);
+      const destination = join(promptDirectory, `${name}.md`);
+      if (!existsSync(template) || !statSync(template).isFile()) {
+        throw new Error(`Missing packaged prompt template: ${template}`);
+      }
+      if (existsSync(destination) && !statSync(destination).isFile()) {
+        throw new Error(`Project prompt is not a file: ${destination}`);
+      }
+      return { template, destination, exists: existsSync(destination) };
+    });
+    let promptParent = promptDirectory;
+    while (!existsSync(promptParent)) promptParent = dirname(promptParent);
+    if (!statSync(promptParent).isDirectory()) {
+      throw new Error(`Prompt directory ancestor is not a directory: ${promptParent}`);
+    }
+    const resolvedPromptDirectory = canonicalPath(promptDirectory);
+    const promptLocal = relative(repository, resolvedPromptDirectory);
+    if (promptLocal === ".." || promptLocal.startsWith("../") || isAbsolute(promptLocal)) {
+      throw new Error(
+        `Prompt directory must remain inside the invoking checkout: ${promptDirectory}`,
+      );
+    }
+    if (promptPlan.some((entry) => !entry.exists) && repository === target) {
+      throw new Error(
+        "Initialize missing prompts from an editable checkout, not the dedicated integration checkout",
+      );
+    }
     const matchingBranch = registeredWorktrees().filter(
       (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
     );
@@ -255,6 +285,15 @@ export async function runCodeless(args: string[]): Promise<void> {
       throw new Error(`Integration worktree target is occupied: ${target}`);
     }
 
+    for (const { template, destination, exists } of promptPlan) {
+      if (exists) {
+        console.log(`Preserved prompt: ${destination}`);
+      } else {
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, readFileSync(template), { flag: "wx" });
+        console.log(`Created prompt: ${destination}`);
+      }
+    }
     if (defaultWorkspace && !stateIgnored) {
       const currentIgnore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
       appendFileSync(
@@ -599,11 +638,6 @@ export async function runCodeless(args: string[]): Promise<void> {
     if (run("git", ["branch", "--show-current"], worktree).trim() !== branch)
       throw new Error(`${worktree} is not on ${branch}`);
     requireClean(worktree, branch);
-    if (
-      run("git", ["rev-parse", "HEAD"], worktree).trim() !==
-      run("git", ["rev-parse", integrationBranch], worktree).trim()
-    )
-      throw new Error(`${branch} is not at the current ${integrationBranch} baseline`);
 
     const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
     const agent = object(result(herdr(["agent", "get", plannerPane]))["agent"], "result.agent");
@@ -930,43 +964,6 @@ export async function runCodeless(args: string[]): Promise<void> {
     console.log(JSON.stringify({ pane, worktree }));
   }
 
-  async function launchPlanner(slug: string): Promise<void> {
-    if (process.env["HERDR_ENV"] !== "1") {
-      throw new Error("Run codeless planner from the stream's Herdr-managed shell");
-    }
-    const documents = join(workspaceRoot, "stream", slug);
-    const worktree = join(workspaceRoot, "worktree", slug);
-    const branch = `stream/${slug}`;
-    for (const file of ["planner.md", "change.md"]) {
-      if (!existsSync(join(documents, file))) throw new Error(`Missing ${join(documents, file)}`);
-    }
-    if (canonicalPath(process.cwd()) !== worktree) {
-      throw new Error(`Planner shell is in ${process.cwd()}, expected ${worktree}`);
-    }
-    if (run("git", ["branch", "--show-current"], worktree).trim() !== branch) {
-      throw new Error(`${worktree} is not on ${branch}`);
-    }
-    const prompt = changePrompt(slug, documents, worktree);
-    const selection = readProject(worktree).planner;
-    await validateRoleSelection("planner", selection, worktree, plannerExtension);
-    console.log(roleSelectionSummary("planner", selection));
-    runVisible(
-      "pi",
-      [
-        "--name",
-        `${slug}-planner`,
-        ...roleSelectionArguments(selection),
-        "--extension",
-        plannerExtension,
-        "--prompt-template",
-        promptDirectory(worktree),
-        "--approve",
-        activationPrompt(prompt),
-      ],
-      worktree,
-    );
-  }
-
   function acquireLandSlot(lock: string, slug: string, base: string): "acquired" | "resumed" {
     let acquired = false;
     try {
@@ -1122,7 +1119,7 @@ export async function runCodeless(args: string[]): Promise<void> {
   }
   const slug = target;
   if (
-    (action !== "create" && action !== "open" && action !== "planner" && action !== "land") ||
+    (action !== "create" && action !== "open" && action !== "land") ||
     slug === undefined ||
     !/^[a-z][a-z0-9-]{0,23}$/.test(slug) ||
     details.length > 0
@@ -1133,10 +1130,6 @@ export async function runCodeless(args: string[]): Promise<void> {
     land(slug);
     return;
   }
-  if (action === "planner") {
-    await launchPlanner(slug);
-    return;
-  }
   if (process.env["HERDR_ENV"] !== "1") {
     throw new Error("Run codeless from a Herdr-managed shell pane");
   }
@@ -1184,33 +1177,104 @@ export async function runCodeless(args: string[]): Promise<void> {
     opened = herdr(["worktree", "open", "--path", worktree, "--label", slug, "--no-focus"]);
   }
 
+  const workspace = id(opened, "workspace", "workspace_id");
+  const plannerPane = id(opened, "root_pane", "pane_id");
+  if (plannerPane === process.env["HERDR_PANE_ID"]) {
+    throw new Error(
+      "Run codeless open from another Herdr shell; the planner pane must be available",
+    );
+  }
+  const planner = `${slug.replaceAll("-", "_")}_planner`;
+  const layout = object(
+    result(herdr(["pane", "layout", "--pane", plannerPane]))["layout"],
+    "result.layout",
+  );
+  const implementerPane = rightPane(layout, plannerPane);
+  const panes = layout["panes"] as JsonObject[];
+  if (panes.length !== (implementerPane === undefined ? 1 : 2)) {
+    throw new Error(
+      "Stream layout must contain only the planner and an optional right-hand implementer pane",
+    );
+  }
+
+  function requireLaunchShell(pane: string): void {
+    const processes = foregroundProcesses(paneProcessInfo(pane));
+    if (processes.length !== 1 || !isShell(processes[0]!)) {
+      throw new Error(`Pane ${pane} must be an available shell before opening the stream`);
+    }
+    if (canonicalPath(string(processes[0]!["cwd"], "shell cwd")) !== worktree) {
+      throw new Error(`Pane ${pane} shell is not in ${worktree}`);
+    }
+  }
+
+  function requireManagedPlanner(agent: JsonObject): void {
+    if (
+      agent["name"] !== planner ||
+      agent["agent"] !== "pi" ||
+      agent["interactive_ready"] !== true
+    ) {
+      throw new Error(
+        `Planner pane ${plannerPane} must contain the Herdr-managed ${planner}; exit an unmanaged agent before reopening`,
+      );
+    }
+    if (canonicalPath(string(agent["foreground_cwd"], "planner foreground cwd")) !== worktree) {
+      throw new Error(`Planner ${planner} is not in ${worktree}`);
+    }
+    const session = object(agent["agent_session"], "planner agent_session");
+    if (
+      agent["screen_detection_skipped"] !== true ||
+      session["source"] !== "herdr:pi" ||
+      session["agent"] !== "pi"
+    ) {
+      throw new Error(
+        "Planner requires Herdr's official Pi lifecycle integration; run herdr integration install pi before reopening",
+      );
+    }
+  }
+
+  if (action === "create" || result(opened)["already_open"] === false) {
+    requirePaneShell(plannerPane, worktree);
+  }
+  const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
+  if (!(plannerProcesses.length === 1 && isShell(plannerProcesses[0]!))) {
+    requireManagedPlanner(
+      object(result(herdr(["agent", "get", plannerPane]))["agent"], "result.agent"),
+    );
+    run("herdr", ["workspace", "focus", workspace]);
+    console.log(`Focused existing planner ${planner}; its session and work remain unchanged.`);
+    return;
+  }
+  requireLaunchShell(plannerPane);
+  if (implementerPane !== undefined) requireLaunchShell(implementerPane);
+
   console.log("Installing project dependencies...");
   const [install, ...installArgs] = readProject(worktree).install;
   run(install, installArgs, worktree);
-
   const selection = readProject(worktree).planner;
   await validateRoleSelection("planner", selection, worktree, plannerExtension);
   console.log(roleSelectionSummary("planner", selection));
 
-  const workspace = id(opened, "workspace", "workspace_id");
-  const plannerPane = id(opened, "root_pane", "pane_id");
-  const split = herdr([
-    "pane",
-    "split",
-    "--pane",
-    plannerPane,
-    "--direction",
-    "right",
-    "--ratio",
-    "0.5",
-    "--cwd",
-    worktree,
-    "--no-focus",
-  ]);
-  id(split, "pane", "pane_id");
-
-  const planner = `${slug.replaceAll("-", "_")}_planner`;
-  run("herdr", [
+  // Recheck after installation/preflight; Herdr owns final interactive readiness.
+  requireLaunchShell(plannerPane);
+  if (implementerPane === undefined) {
+    const split = herdr([
+      "pane",
+      "split",
+      "--pane",
+      plannerPane,
+      "--direction",
+      "right",
+      "--ratio",
+      "0.5",
+      "--cwd",
+      worktree,
+      "--no-focus",
+    ]);
+    requirePaneShell(id(split, "pane", "pane_id"), worktree);
+  } else {
+    requireLaunchShell(implementerPane);
+  }
+  const started = herdr([
     "agent",
     "start",
     planner,
@@ -1228,10 +1292,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     promptDirectory(worktree),
     "--approve",
   ]);
+  requireManagedPlanner(object(result(started)["agent"], "result.agent"));
   run("herdr", [
     "agent",
     "prompt",
-    planner,
+    plannerPane,
     activationPrompt(changePrompt(slug, documents, worktree)),
   ]);
   run("herdr", ["workspace", "focus", workspace]);