@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/agents/ralph/pi/{polling.md → wake.md}

@@ -1,4 +1,8 @@
-## Spawning subagents (PI)
+## Wake mechanism (PI — blocking wait)
+
+**Mechanism: a blocking wait — `wait_for_agents` blocks until at least one background worker finishes and returns its result inline, so the wait itself is the completion signal and no timer, sleep, or poll loop exists.**
+
+### Spawn
 
 RALPH HAS ONLY ONE WAY TO SPAWN SUBAGENTS: call the **`task`** tool (not bash, not any other tool).
 
@@ -10,7 +14,7 @@ Example:
 ```
 Calling tool 'task' with arguments: { "prompt": "...", "cwd": ".agent-cortex/worktrees/abc-123" }
 ```
-The response is a plain agent ID string (e.g. `agent-550e8400-e29b-41d4-a716-446655440000`). Store it in memory — you need it later to wait for the result.
+The response is a plain agent ID string (e.g. `agent-550e8400-e29b-41d4-a716-446655440000`). Store it in memory and in `state.json` — you need it later to wait for the result.
 
 **`wait_for_agents`** — Block until at least one background sub-agent completes. This is the primary way to get results back.
 - `agentIds` (string[], required): The agent IDs returned by `task` to wait on.
@@ -31,25 +35,20 @@ Rules:
 - ALWAYS set `cwd` to the feature worktree path when running stage chores.
 - ALWAYS keep the returned `agentId` in memory to wait on it / read its result later.
 
-## Completion detection (PI)
+### Completion arrival
 
-PI detects subagent completion with a blocking wait, not polling: after dispatching, call `wait_for_agents` with every in-flight agent ID. It returns as soon as at least one agent completes, with that agent's result ready to process. Do not `sleep`, do not start background timers — the wait tool IS the completion mechanism.
+A completion arrives **in the wait response**: `wait_for_agents` returns as soon as one worker finishes, carrying that worker's result inline, so you never go looking for it. Apply the shared completion handling in the **Event loop** section of agent.md (the result is included in the wait response, or re-read with `read_agent`; re-read state.json and branch on the entry's `kind` — `stage` parses the REPORT and confirms the worker closed its chore, `expand` confirms the parent now has `stage:*` chores and dispatches the ready `stage:code` — then check for newly ready beads and the shutdown check). An expansion worker is in the wait set but is never treated as a chore: it emits no REPORT and needs no close confirmation.
 
-### Wait loop lifecycle
+### Id tracking
 
-- **Dispatch-and-wait** — during initialization, dispatch up to 5 AFK chore subagents with `task` and hold their agent IDs (recorded in `state.json`'s `inflight` list).
-- **Wait** — call `wait_for_agents` with the agent IDs of every in-flight chore (`timeout` defaults to 120s). The tool blocks until at least one finishes. For each completed agent:
-  1. Flush its log tail if it has new lines (see _Log polling_ below) to surface progress to chat.
-  2. Apply the shared completion handling in the **Event loop** section of agent.md (the result is included in the wait response, or re-read with `read_agent`; re-read state.json, parse the REPORT, close the chore, advance the parent, check for newly ready beads, run the shutdown check).
-  3. Drop the completed agent ID from the wait set.
-- **Repeat** — dispatch replacements for completed chores (up to 5 in flight), add their new IDs to the wait set, and call `wait_for_agents` again with the remaining + new IDs.
-- **Timeout / STILL RUNNING** — if the timeout elapses with agents still working, the tool returns those agents as STILL RUNNING (with `timed out` noted). Call `wait_for_agents` again with the same IDs — the still-running agents keep working; you never re-dispatch them. `read_agent` remains available to re-read a completed result at any time.
-- **Abort** — if the user aborts, `wait_for_agents` returns immediately with what is known so far (no hang); do not re-issue the wait.
-- **Stop** — when stopping completely (HITL Pause or Shutdown) there is no timer to kill on PI: just stop calling `wait_for_agents`. Never start background `sleep` timers for completion detection.
+Initialize `.agent-cortex/ralph/state.json` as `{ "timerShellId": null, "inflight": [] }`. Only one handle matters here:
 
-## Log polling
+- **inflight[].agentId** — the ID `task` returned for that worker; it is the argument `wait_for_agents` takes, the identifier for a `read_agent` fallback, and the key the completion is correlated to its bead.
+- **timerShellId** — stays `null` on PI forever: the blocking wait replaces a poll timer, so nothing is ever recorded there.
 
-Run this procedure each time `wait_for_agents` returns (or whenever a new agent is dispatched):
+### Log flush
+
+Flush new log lines as part of handling each wait result — that is when the loop wakes, and a worker's final lines arrive with the completion. Run this procedure each time `wait_for_agents` returns (or whenever a new agent is dispatched):
 
 1. **Query in-flight beads**: read `inflight` from `state.json`. Each entry has a `parentId` and `logLine`.
 2. For each in-flight entry, read new lines from its log file:
@@ -66,9 +65,25 @@ Run this procedure each time `wait_for_agents` returns (or whenever a new agent
    - Update `logLine` in `state.json` for that entry.
 4. If no entry had new lines, post nothing — do not spam the chat with empty polls.
 
-## Polling constraints
+### Wait loop lifecycle
+
+- **Dispatch-and-wait** — during initialization, dispatch up to 5 AFK chore subagents with `task` (or an expansion worker for a chore-less AFK bead) and hold their agent IDs (recorded in `state.json`'s `inflight` list; expansion entries carry `kind: "expand"` and `choreId: null`).
+- **Wait** — call `wait_for_agents` with the agent IDs of every in-flight agent, stage worker or expansion worker (`timeout` defaults to 120s). The tool blocks until at least one finishes. For each completed agent:
+  1. Flush its log tail if it has new lines (see _Log flush_ above) to surface progress to chat.
+  2. Apply the shared completion handling described under _Completion arrival_ above.
+  3. Drop the completed agent ID from the wait set.
+- **Repeat** — dispatch replacements for completed work (up to 5 in flight), add their new IDs to the wait set, and call `wait_for_agents` again with the remaining + new IDs. A completed expansion leaves a slot to fill with its parent's newly ready `stage:code` chore.
+- **Empty wait set** — never call `wait_for_agents` with an empty `agentIds` list. When handling a completion leaves `inflight` empty, run the event loop's final check (agent.md, _If nothing remains in flight_): a ready `stage:*` chore, or a ready, claimable chore-less AFK task bead (expand it first), is dispatchable — dispatch it and wait again. With nothing dispatchable, pending HITL gate beads mean **HITL Pause** and none mean **Shutdown**; either way stop calling `wait_for_agents` and act again only when the user re-prompts.
+- **Timeout / STILL RUNNING** — if the timeout elapses with agents still working, the tool returns those agents as STILL RUNNING (with `timed out` noted). Call `wait_for_agents` again with the same IDs — the still-running agents keep working; you never re-dispatch them. `read_agent` remains available to re-read a completed result at any time.
+- **Abort** — if the user aborts, `wait_for_agents` returns immediately with what is known so far (no hang); do not re-issue the wait.
+
+### Stop
+
+Nothing to kill: stopping means simply **stop calling `wait_for_agents`**. There is no timer, so there is no shellId to kill and nothing to unset — just do not issue another wait. Never start background `sleep` timers as a substitute for the wait, and never re-issue a wait once the HITL pause or shutdown condition has been met.
+
+### Waiting constraints
 
-- **Always** keep a `wait_for_agents` call outstanding while agents are in-flight — never let running agent work stall without a wait active.
+- **Always** keep a `wait_for_agents` call outstanding while agents are in-flight — stage workers and expansion workers alike. Never let running agent work stall without a wait active.
 - **Never** re-dispatch an agent that is merely STILL RUNNING — wait again on the same ID.
-- **Never** start `sleep` / background timer loops for completion detection on PI — `wait_for_agents` replaces them. There is nothing to kill on HITL Pause for PI.
-- **Never** post empty poll updates to chat — only surface new log content.
+- **Never** start `sleep` / background timer loops for completion detection on PI — `wait_for_agents` replaces them, and there is nothing to kill on HITL Pause.
+- **Never** post empty poll updates to chat — only surface new log content.

package/agents/ralph-plan/agent.md

@@ -51,23 +51,35 @@ Update the top-level bead's `design` field with a high-level implementation plan
 ### 6. Decompose into tasks
 For large workstreams (multiple distinct areas) invoke the **prd-to-tasks** skill. For a single self-contained task invoke **create-task**. Pass the full `bd prime` output and any relevant design context from the `design` field to each skill.
 
-For each new feature bead and each new task bead, create a HITL planning gate before handoff. The feature/task bead depends on this gate and stays blocked until the user explicitly confirms planning is sufficient **for that specific feature/task**.
+**Planning gate.** Each feature carries exactly one HITL planning bead — the design gate that keeps the feature's implementation children out of `bd ready` until a human confirms planning is sufficient. It is the bead `create-task` builds on its feature path: that skill's steps 5–6 are the authority for this shape, so when you delegate the feature to `create-task` the gate already exists and you must not create a second one.
 
-Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
+Ownership is `--parent`; ordering is `bd dep add`. The planning bead is **owned by the feature** and **blocks every implementation child** of that feature. The feature never depends on its own gate — a container that waits on its own child is neither owner nor ordering.
+
+Every planning bead description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
+
+Both routes above create the gate for you, so this block is the shape to build by hand only when the feature already exists and `bd children <feature-id>` lists no `Plan:` child. Never run it beside a gate `create-task` already made: bead creation is not idempotent, so a second run leaves two design gates blocking the same children. The guard is check-then-act and therefore not atomic — two planners on one feature at the same instant could both pass it and create a gate each; that is acceptable because the only automated creation path goes through `create-task`, this agent runs as a single interactive HITL session, and a stray second planning bead carries no `lifecycle:feature-pr`, so ralph never pauses on it.
 
 ```bash
-gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>
+# Design gate: human-owned, owned by the feature, blocking every implementation child.
+planning_id=$(bd create "Plan: <feature title>" --type task --priority <priority> \
+  -l execution:hitl --parent <feature-id> --no-inherit-labels \
+  --description "<planning context, decisions, open questions, and references>
 
 ## Acceptance Criteria
 
-- [ ] User confirms planning is sufficient for this feature/task." --validate)
-bd tag <planning-gate-id> implementation-type:hitl
-bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
+- [ ] The user confirms planning is sufficient for this feature." --validate --silent)
+
+# Readiness gate: every implementation child waits on the design gate.
+bd dep add <impl-task-id> <planning-bead-id>
 ```
 
-Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
+`--no-inherit-labels` is not optional: `bd` copies a parent's labels at create time, so without it a gate under an `execution:afk` feature picks up `execution:afk` beside its own `execution:hitl` and stops routing as human work.
+
+A planning bead is **not** a PR gate and carries no `lifecycle:` label. `create-chores.mjs` owns the `lifecycle:feature-pr` gate — owned by the implementation task, blocked by its `document` chore (the `create-task` skill's `REFERENCE.md` → PR gate bead); creating one here would put a second, differently-wired gate on the same bead. A standalone task bead needs no planning bead: `create-task` classifies it, and its human checkpoint is that PR gate.
+
+Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature is ready to implement; leave all unconfirmed gates open and blocking.
 
-Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
+Before handing off, ensure every bead created in this step carries an `execution:` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates are labelled inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
 
 Tag every bead created in this step with `workflow:ralph`:
 
@@ -95,12 +107,12 @@ bead against the full backlog — a P3 feature that blocks others may need a hig
 explicit priority than a standalone P4 feature.
 
 ### 7. Agree with the user
-Present the bead list (IDs, titles, one-line rationale each) plus planning gate status for each item using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
+Present the bead list (IDs, titles, one-line rationale each) plus the planning-gate status of each feature using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
 
-If any planning gates remain open, include an explicit warning that those features/tasks are still blocked and cannot be handed off to ralph yet. Iterate until approved.
+If any planning gate remains open, include an explicit warning that its implementation children are still blocked by it and cannot be handed off to ralph yet. Iterate until approved.
 
 ### 8. Hand off to ralph
-Once approved, report: "Plan complete — `bd ready` will show the first tasks for ralph."
+Once approved, report: "Plan complete — `bd ready -l execution:afk` will show the first tasks for ralph."
 
 ## Exploration sub-agent instructions
 

package/bin/agent-cortex.mjs

@@ -2,8 +2,13 @@
 
 import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
 import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
 import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mjs";
 
+/** @typedef {import("./installers/pi.mjs").InstallPiResult} InstallPiResult */
+/** @typedef {import("./installers/pi.mjs").RegisterPiResult} RegisterPiResult */
+
 const argv = process.argv.slice(2);
 const parsed = parseArgs(argv);
 
@@ -12,6 +17,41 @@ if (parsed.command === "help") {
   process.exit(0);
 }
 
+/**
+ * Read the version of the package this CLI ships in: `bin/` sits one level below
+ * the package root, in the repo checkout and in the published tarball alike.
+ * Resolved from this file's own location, never from the cwd or node_modules
+ * resolution, so an installed CLI reports the version it was installed at.
+ * Throws when that manifest is missing, unreadable, malformed, or has no version
+ * string, so a broken install never prints a bogus version with a success exit.
+ * @returns {Promise<string>}
+ */
+async function readPackageVersion() {
+  const manifestPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  /** @type {unknown} */
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Cannot read the package version from ${manifestPath}: ${/** @type {Error} */ (err).message}`);
+  }
+  const version = /** @type {{ version?: unknown }} */ (manifest).version;
+  if (typeof version !== "string" || version === "") {
+    throw new Error(`Cannot read the package version from ${manifestPath}: the manifest has no "version" string.`);
+  }
+  return version;
+}
+
+if (parsed.command === "version") {
+  try {
+    process.stdout.write(`${await readPackageVersion()}\n`);
+  } catch (err) {
+    process.stderr.write(`${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (parsed.command === "unknown") {
   process.stderr.write(`Unknown command: ${parsed.name}\nRun "agent-cortex --help" for usage.\n`);
   process.exit(1);
@@ -66,7 +106,7 @@ if (parsed.command === "install") {
         process.stdout.write(`  → register it with pi: pi install ${result.output}\n`);
       }
     } catch (err) {
-      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
       process.exit(1);
     }
     process.exit(0);
@@ -99,8 +139,11 @@ if (parsed.command === "install") {
       // keeps generating only (documented in --help).
       if (parsed.output === undefined) {
         await registerClaude({
-          root: result.marketplaceRoot,
-          manifest: result.marketplaceManifest,
+          // A default install always materialises the marketplace manifest; the
+          // generate-only form (--output) is the only path where it is null, and
+          // this branch is not that path.
+          root: /** @type {string} */ (result.marketplaceRoot),
+          manifest: /** @type {object} */ (result.marketplaceManifest),
           pluginVersion: result.pluginVersion,
           dryRun: parsed.dryRun ?? false,
           requireRegister: parsed.requireRegister ?? false,
@@ -108,12 +151,13 @@ if (parsed.command === "install") {
       }
       process.exit(0);
     } catch (err) {
-      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
       process.exit(1);
     }
   }
 }
 
+/** @param {{ removed: string[] }} result */
 function printPiSweep({ removed }) {
   if (removed.length === 0) return;
   process.stdout.write(
@@ -124,6 +168,24 @@ function printPiSweep({ removed }) {
   }
 }
 
+if (parsed.command === "migrate") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
+
+  // Loaded lazily: the migration registry is only needed on this path.
+  const { runMigrate } = await import("../scripts/lib/migrate.mjs");
+  try {
+    await runMigrate({ apply: parsed.apply ?? false, dir: parsed.dir });
+  } catch (err) {
+    process.stderr.write(`Migration failed: ${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+/** @param {InstallPiResult} result */
 function printPiInstall(result) {
   process.stdout.write(`Installing agent-cortex for "pi" harness…\n`);
   process.stdout.write(`  ✓ Staged pi package → ${result.output}\n`);