@dpeek/codeless 0.1.4 → 0.1.5

package/README.md

@@ -100,17 +100,20 @@ 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 and verifies
-the `<slug>_planner` Herdr identity, managed interactive readiness, foreground
-worktree, and Herdr's official Pi lifecycle authority and session reporter. 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`. Pi's active command context
-owns the live conversation identity. Codeless requires Herdr's official reporter
-but treats its native session-reference value as asynchronous restore metadata,
-not an activation prerequisite. Global
+The package-owned planner extension admits each newly launched planner using
+its exact `<slug>-planner` Pi name, `<slug>_planner` Herdr identity, managed
+readiness, canonical worktree, and official Pi lifecycle integration. It checks
+that all five planner tools are active before sending `/change` and binds the
+admitted process, pane, worktree, name, and live session ID.
+
+After landing, replacement activation uses a one-use ticket held in that Pi
+process, bound to the new conversation's session ID. It verifies the local
+identity, effective model/thinking selection, and tools without querying Herdr's
+asynchronous status. Saved session entries cannot replay a handoff. Codeless
+requires activation acknowledgement before submitting `/change` exactly once;
+failed or cancelled handoffs never retry automatically. After a failed
+replacement, exit Pi and reopen the stream from another Herdr shell. Herdr's
+integration still supplies monitoring and external agent control. 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
@@ -235,9 +238,9 @@ 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 the names, process, lifecycle
-authority, and worktree without correlating Herdr's asynchronous restore
-reference to Pi's live session; it never renames an unmanaged process. There is
+Herdr's managed agent name. Launch admission verifies both names, lifecycle
+authority, and worktree; subsequent conversation replacements use the local
+handoff described above. Codeless never renames an unmanaged process. There is
 no direct `planner` command.
 
 Dispatch validates the implementer selection before touching the planner's

package/extension/planner.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { validAttempt } from "../src/attempt.ts";
 
 const codeless = fileURLToPath(new URL("../bin/codeless", import.meta.url));
@@ -28,32 +29,66 @@ function selection(value) {
   return { provider: value.provider, model: value.model, thinking: value.thinking };
 }
 
+// Pi reloads extension modules when replacing a session. Keep only in-flight
+// tickets on the process global; neither persisted entries nor a module cache
+// can establish handoff provenance. Every ticket is removed on consume/finally.
+const handoffKey = Symbol.for("@dpeek/codeless/planner-handoffs");
+const handoffs = (globalThis[handoffKey] ??= new Map());
+
+function worktree(cwd) {
+  try {
+    return realpathSync(cwd);
+  } catch {
+    throw new Error("Codeless could not resolve the planner worktree");
+  }
+}
+
 export default function plannerExtension(pi) {
   let registered = false;
   let pending;
+  let admitted;
 
   pi.registerCommand("streams-activate", {
     description: "Verify this planner session before starting its project prompt",
     handler: async (args, ctx) => {
-      let prompt;
+      let input;
       try {
-        prompt = JSON.parse(args);
+        input = JSON.parse(args);
       } catch {
-        throw new Error("Codeless activation requires one JSON-quoted project prompt");
+        throw new Error("Codeless activation requires a JSON prompt or handoff ticket");
       }
-      if (typeof prompt !== "string" || !prompt.startsWith("/change ")) {
+      const replacement = typeof input === "object" && input !== null;
+      const ticket = replacement ? handoffs.get(input.handoff) : undefined;
+      if (replacement) {
+        handoffs.delete(input.handoff);
+        if (!ticket) throw new Error("Codeless handoff is missing, expired, or already consumed");
+      } else if (typeof input !== "string" || !input.startsWith("/change ")) {
         throw new Error("Codeless activation requires a /change project prompt");
       }
-      const activation = ctx.sessionManager
-        .getEntries()
-        .findLast(
-          (entry) =>
-            entry.type === "custom" &&
-            entry.customType === "streams-role-selection" &&
-            entry.data?.role === "planner",
-        );
-      if (activation) {
-        const requested = selection(activation.data.selection);
+      if (admitted) throw new Error("Codeless planner session is already activated");
+      const sessionName = pi.getSessionName();
+      const match = /^([a-z][a-z0-9-]{0,23})-planner$/.exec(sessionName ?? "");
+      if (!match)
+        throw new Error("Codeless activation requires an exact <slug>-planner Pi session name");
+      const expectedPlanner = `${match[1].replaceAll("-", "_")}_planner`;
+      const pane = process.env.HERDR_PANE_ID;
+      if (!pane) throw new Error("Codeless activation requires a Herdr-managed planner pane");
+      const cwd = worktree(ctx.cwd);
+      const sessionId = ctx.sessionManager.getSessionId();
+      if (replacement) {
+        if (
+          ticket.binding.pid !== process.pid ||
+          ticket.binding.pane !== pane ||
+          ticket.binding.cwd !== cwd ||
+          ticket.binding.sessionName !== sessionName ||
+          ticket.sessionId !== sessionId ||
+          ticket.binding.sessionId === sessionId
+        ) {
+          throw new Error(
+            "Codeless handoff does not match this planner process, pane, worktree, or session",
+          );
+        }
+        const requested = ticket.selection;
         const reference = `${requested.provider}/${requested.model}`;
         const model = ctx.modelRegistry.find(requested.provider, requested.model);
         if (!model) throw new Error(`Planner requested ${reference}, but Pi could not find it`);
@@ -66,56 +101,46 @@ export default function plannerExtension(pi) {
           ctx.model.id !== requested.model ||
           pi.getThinkingLevel() !== requested.thinking
         ) {
-          const effective = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no model";
           throw new Error(
-            `Planner requested ${reference} at thinking level ${requested.thinking}, but Pi applied ${effective} at ${pi.getThinkingLevel()}`,
+            `Codeless planner could not apply ${reference} at thinking level ${requested.thinking}`,
           );
         }
-      }
-      const sessionName = pi.getSessionName();
-      const match = /^([a-z][a-z0-9-]{0,23})-planner$/.exec(sessionName ?? "");
-      if (!match)
-        throw new Error("Codeless activation requires an exact <slug>-planner Pi session name");
-      const expectedPlanner = `${match[1].replaceAll("-", "_")}_planner`;
-      const pane = process.env.HERDR_PANE_ID;
-      if (!pane) throw new Error("Codeless activation requires a Herdr-managed planner pane");
-      const plannerIdentity = async () => {
-        const identity = await pi.exec("herdr", ["agent", "get", pane], { timeout: 30_000 });
-        if (identity.code !== 0) {
+      } else {
+        const plannerIdentity = async () => {
+          const identity = await pi.exec("herdr", ["agent", "get", pane], { timeout: 30_000 });
+          if (identity.code !== 0) {
+            throw new Error(
+              identity.stderr.trim() ||
+                identity.stdout.trim() ||
+                "Codeless could not verify Herdr planner identity",
+            );
+          }
+          try {
+            return JSON.parse(identity.stdout).result?.agent;
+          } catch {
+            throw new Error("Herdr returned an invalid planner identity response");
+          }
+        };
+        const agent = await plannerIdentity();
+        if (agent?.name !== expectedPlanner) {
           throw new Error(
-            identity.stderr.trim() ||
-              identity.stdout.trim() ||
-              "Codeless could not verify 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`,
           );
         }
-        try {
-          return JSON.parse(identity.stdout).result?.agent;
-        } catch {
-          throw new Error("Herdr returned an invalid planner identity response");
+        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" || worktree(agent.foreground_cwd) !== cwd) {
+          throw new Error("Codeless planner worktree does not match Herdr's foreground cwd");
+        }
+        const session = agent.agent_session;
+        if (
+          agent.screen_detection_skipped !== true ||
+          session?.source !== "herdr:pi" ||
+          session.agent !== "pi"
+        ) {
+          throw new Error("Codeless planner requires Herdr's Pi lifecycle integration");
         }
-      };
-      const agent = await plannerIdentity();
-      if (agent?.name !== expectedPlanner) {
-        throw new Error(
-          `Codeless planner identity is ${agent?.name ?? "missing"}, expected ${expectedPlanner}; exit this agent and run codeless open ${match[1]} from another Herdr shell`,
-        );
-      }
-      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;
-      if (
-        agent.screen_detection_skipped !== true ||
-        session?.source !== "herdr:pi" ||
-        session.agent !== "pi"
-      ) {
-        throw new Error("Codeless planner requires Herdr's Pi lifecycle integration");
       }
       const activeTools = ctx.getSystemPromptOptions().selectedTools ?? [];
       const missing = requiredTools.filter((tool) => !activeTools.includes(tool));
@@ -124,8 +149,10 @@ export default function plannerExtension(pi) {
           `Codeless planner activation is missing required tools: ${missing.join(", ")}`,
         );
       }
+      admitted = { pid: process.pid, pane, cwd, sessionName, sessionId };
       ctx.ui.notify(`Planner activated: ${sessionName} / ${expectedPlanner}`, "info");
-      pi.sendUserMessage(prompt, { expandPromptTemplates: true });
+      if (ticket) ticket.activated = true;
+      else pi.sendUserMessage(input, { expandPromptTemplates: true });
     },
   });
 
@@ -135,8 +162,18 @@ export default function plannerExtension(pi) {
       if (!pending || pending.running) throw new Error("No pending Codeless handoff");
       const request = pending;
       request.running = true;
+      let token;
       try {
         await ctx.waitForIdle();
+        if (
+          !admitted ||
+          admitted.pid !== process.pid ||
+          admitted.pane !== process.env.HERDR_PANE_ID ||
+          admitted.cwd !== worktree(ctx.cwd) ||
+          admitted.sessionId !== ctx.sessionManager.getSessionId() ||
+          admitted.sessionName !== pi.getSessionName()
+        )
+          throw new Error("Codeless handoff requires the activated planner session");
         const execution = await pi.exec(
           "bun",
           [codeless, "next", request.changePath, request.landedCommit],
@@ -160,23 +197,39 @@ export default function plannerExtension(pi) {
           throw new Error("Codeless returned an invalid planner handoff");
         }
         const requested = selection(requestedValue);
+        token = randomUUID();
+        const ticket = {
+          binding: admitted,
+          selection: requested,
+          sessionId: undefined,
+          activated: false,
+        };
+        handoffs.set(token, ticket);
         const result = await ctx.newSession({
           setup: async (sm) => {
             sm.appendSessionInfo(sessionName);
-            sm.appendCustomEntry("streams-role-selection", {
-              role: "planner",
-              selection: requested,
-            });
+            ticket.sessionId = sm.getSessionId();
           },
           withSession: async (replacement) => {
-            await replacement.sendUserMessage(`/streams-activate ${JSON.stringify(prompt)}`, {
-              expandPromptTemplates: true,
-            });
+            await replacement.sendUserMessage(
+              `/streams-activate ${JSON.stringify({ handoff: token })}`,
+              {
+                expandPromptTemplates: true,
+              },
+            );
+            // Pi displays command errors instead of rejecting sendUserMessage.
+            // Require an explicit receipt before submitting the project prompt.
+            if (!ticket.activated)
+              throw new Error(
+                "Codeless replacement activation failed; exit Pi and reopen the stream",
+              );
+            await replacement.sendUserMessage(prompt, { expandPromptTemplates: true });
           },
         });
         if (result.cancelled)
           throw new Error("Codeless handoff cancelled; the current session was retained");
       } finally {
+        if (token) handoffs.delete(token);
         pending = undefined;
       }
     },
@@ -212,6 +265,7 @@ export default function plannerExtension(pi) {
         additionalProperties: false,
       },
       async execute(_toolCallId, params) {
+        if (!admitted) throw new Error("Codeless handoff requires an activated planner");
         if (pending) throw new Error("A Codeless handoff is already pending");
         pending = {
           changePath: params.changePath.replace(/^@/, ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpeek/codeless",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "An attended planner and implementer workflow for parallel capability development",
   "homepage": "https://github.com/dpeek/codeless#readme",
   "bugs": {

package/spec/workflow.md

@@ -137,26 +137,39 @@ 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, Herdr's official Pi
-lifecycle authority and reporter, and the active planner tools. A wrong name,
-process, lifecycle source, worktree, or tool set stops visibly before `/change`.
-Activation never repairs names. Pi's active command context owns the live
-conversation identity. Codeless requires Herdr's official session reporter but
-treats its native session-reference value as asynchronous restore metadata; it
-does not correlate that value with the active Pi session or wait for a changed
-value. 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 the replacement's Pi
-name, selection, tools, and Herdr process/lifecycle/worktree binding before
-prompting it. 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.
+The package-owned extension admits a newly launched planner after checking its
+exact `<slug>-planner` Pi name, `<slug-with-hyphens-replaced>_planner` Herdr
+name, managed interactive readiness, canonical foreground worktree, official Pi
+lifecycle authority and reporter, and active planner tools. Admission binds the
+process ID, pane, canonical worktree, planner name, and native Pi session ID.
+Activation never repairs names or submits the initial prompt twice. The direct
+`planner` command is removed; recovery exits Pi deliberately and reopens from
+another Herdr shell.
+
+Post-landing conversation replacement uses that admission, without querying
+Herdr. After idle and workflow validation, Codeless creates a one-use in-memory
+handoff ticket for the admitted parent and requested model/thinking selection.
+Pi's `newSession` setup binds it to the newly allocated native session ID;
+`withSession` invokes activation in the fresh extension. Activation consumes the
+ticket before checking the same process, pane, canonical worktree and planner
+name, a distinct matching replacement session, effective selection, and active
+tools. Saved session entries cannot authorize a handoff. The ticket registry
+survives Pi's extension module reload within the process, but no ticket survives
+consumption, cancellation, failure, or process exit.
+
+Pi displays extension-command errors without rejecting the command submission.
+Codeless therefore requires an explicit activation acknowledgement before
+`withSession` submits the project prompt exactly once through the replacement
+context. Missing acknowledgement stops visibly. Neither old Pi contexts nor
+Herdr's asynchronous lifecycle or native-session snapshots participate in
+replacement activation. Delayed, missing, or rejected lifecycle reports cannot
+block this local handoff. Cancellation retains the old conversation; failed
+replacement requires deliberate exit and reopen, with no automatic retry.
+
+Herdr's official Pi integration remains responsible for lifecycle monitoring,
+external agent control, and native-session restore reporting. Implementers use
+the corresponding `_impl` and `-impl` names. Codeless loads its own extension
+explicitly. This boundary was checked against Herdr 0.8.2 and Pi 0.85.1.
 
 ## Dispatch and review