@mrciphersmith/keryx 0.2.145 → 0.2.149

package/README.md

@@ -260,7 +260,12 @@ What is in it today:
   blocked ids, and the plan file it lives in. A plan can also be published FOR
   APPROVAL — items marked `proposed` await a human, never force the agent to
   continue, and are shown as `◇ awaiting approval` in both the sidebar and the
-  modal.
+  modal. Orchestrators publish into this same view — `job-orchestrator`,
+  `flow-orchestrator`, `review-orchestrator`, `issue-analyzer`,
+  `feature-analyzer`, `autodoc-orchestrator`, `docpack-orchestrator`,
+  `feature-dev` and `review-pr-feedback` project their own steps here under the
+  `session-plan-bridge` rule, so a run driven by one of them is watchable while
+  it runs instead of only after it reports.
 - **Theme-aware rich transcripts.** Assistant prose, headings, emphasis,
   inline code, fenced code, diffs, and GFM pipe tables use semantic colors
   derived from the selected `/theme`. Use a language fence such as

package/dist/cli.js

@@ -30207,15 +30207,49 @@ ${shown.join(`
       const risk = toolByName.get(call.name)?.definition.risk;
       const isPureReadTool = risk === "read" && !DURABLE_READ_TOOL_NAMES.has(call.name);
       if (!isPureReadTool && untrustedContentSeen) {
-        const result = {
-          output: "tool blocked: external web content cannot authorize further tool calls in this turn",
-          isError: true
-        };
-        io.onToolResult?.(call.name, result);
-        history.push({ role: "tool", content: result.output, provenance: "tool", toolCallId: call.id, ts: now() });
-        io.onHistoryChange?.("tool");
-        gateBlockedAny = true;
-        continue;
+        const approver = io.requestApproval;
+        if (deps.unattended === true || approver === undefined) {
+          const result = {
+            output: "tool blocked: external web content cannot authorize further tool calls in this turn",
+            isError: true
+          };
+          io.onToolResult?.(call.name, result);
+          history.push({ role: "tool", content: result.output, provenance: "tool", toolCallId: call.id, ts: now() });
+          io.onHistoryChange?.("tool");
+          gateBlockedAny = true;
+          continue;
+        }
+        const taintFingerprint = toolCallHash(call.name, call.input);
+        let taintApproved;
+        try {
+          const response = await approver(call.name, call.input, {
+            fingerprint: taintFingerprint,
+            destructive: risk === "destructive",
+            untrustedOrigin: true
+          });
+          taintApproved = isApprovalFor(response, taintFingerprint);
+        } catch (err) {
+          const result = {
+            output: `${call.name} not executed: the approval prompt failed (${err instanceof Error ? err.message : String(err)})`,
+            isError: true
+          };
+          io.onToolResult?.(call.name, result);
+          history.push({ role: "tool", content: result.output, provenance: "tool", toolCallId: call.id, ts: now() });
+          io.onHistoryChange?.("tool");
+          gateBlockedAny = true;
+          continue;
+        }
+        if (!taintApproved) {
+          const result = {
+            output: "tool blocked: external web content cannot authorize this call, and the user did not authorize it either",
+            isError: true
+          };
+          io.onToolResult?.(call.name, result);
+          history.push({ role: "tool", content: result.output, provenance: "tool", toolCallId: call.id, ts: now() });
+          io.onHistoryChange?.("tool");
+          gateBlockedAny = true;
+          continue;
+        }
       }
       io.onToolCall?.(call.name, call.input);
       const reservation = reservationByCallId.get(call.id) ?? reserveToolAttempt(budget, call.name, call.input);
@@ -51463,7 +51497,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.145",
+  version: "0.2.149",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -88755,6 +88789,9 @@ function renderUseToolApprovalLines(description, meta) {
   if (meta?.destructive === true) {
     lines.push("  this tool is treated as destructive \u2014 it is a third party's code");
   }
+  if (meta?.untrustedOrigin === true) {
+    lines.push("  \u26A0 follows untrusted external content \u2014 that content cannot authorize this call");
+  }
   return lines;
 }
 function summariseUseToolApproval(description) {
@@ -103198,6 +103235,10 @@ function formatPlanMeta(plan, dir) {
     "",
     "Storage   <session>/plan.json \u2014 a sibling of slate.json, so a completed",
     "          Flow closing its slate can no longer take the plan with it.",
+    "",
+    "Note      This is the agent's own plan for this session. The `/plan on|off`",
+    "          COMMAND is a different thing \u2014 the session's read-only mode, which",
+    "          this view neither shows nor changes.",
     ...dir === undefined ? [] : [`Session   ${dir}`]
   ].join(`
 `);
@@ -103265,7 +103306,7 @@ function presentExecutionPlanInspector(openModalFn, otui, chrome, options) {
   };
   let unsubscribe;
   const handle = openModalFn(otui, chrome, {
-    title: "/plan",
+    title: "Session plan",
     tabs: [
       { id: "plan", label: "Plan" },
       { id: "meta", label: "Meta" }
@@ -104086,6 +104127,7 @@ function attachUsageIo(io, chrome) {
       totalOut = 0;
       chrome.setHeaderMeta("\u21910 \u21930");
       chrome.setContextTotal(0);
+      chrome.setUsage?.(0, 0);
     }
   });
 }
@@ -105754,6 +105796,12 @@ async function launchTuiAgentShell(opts) {
     };
     const approvalContext = createApprovalContextLoader(opts.session?.cwd ?? process.cwd());
     io.requestApproval = async (tool, inputJson, meta) => {
+      if (meta?.untrustedOrigin === true) {
+        transcript.add(new otui.TextRenderable(r, {
+          id: `ap${uid++}`,
+          content: otui.t`${otui.yellow("\u26A0 follows untrusted external content \u2014 it cannot authorize this call; your answer does")}`
+        }));
+      }
       if (tool === "spawn_subagent") {
         let mode = "read_only";
         let taskPreview = inputJson;
@@ -109713,6 +109761,13 @@ ${GUTTER}${style.dim(formatReasoningOneLiner({
     },
     requestApproval: async (tool, input, meta) => {
       stopSpinner();
+      if (meta?.untrustedOrigin === true) {
+        out(`
+${GUTTER}${style.red("\u26A0 this call follows untrusted external content in this turn")}
+`);
+        out(`${GUTTER}${style.dim("that content cannot authorize it \u2014 only your answer can")}
+`);
+      }
       if (tool === "apply_patch") {
         const patch = extractPatchText(input);
         out(`
@@ -118202,6 +118257,16 @@ async function main() {
   }
   const route = CLI_ROUTES[command];
   if (route) {
+    if (shouldInterceptHelp(command, args.slice(1))) {
+      const usage = groupUsage(command);
+      console.log(usage === undefined ? `keryx ${VERSION2}
+
+${USAGE_BODY}` : `keryx ${command} \u2014 usage:
+
+${usage}
+`);
+      return;
+    }
     await route(args.slice(1));
     return;
   }
@@ -118209,10 +118274,7 @@ async function main() {
   printHelp25();
   process.exitCode = 1;
 }
-function printHelp25() {
-  console.log(`keryx ${VERSION2}
-
-Usage:
+var USAGE_BODY = `Usage:
   keryx                                        Show CLI usage
   keryx shell [-c|--continue] [-r|--resume [id]] [--provider <p>] [--model <m>] [--base-url <url>] [--agent|--chat] [--tui|--no-tui]
                                                Start TUI agent shell (sessions are per-project)
@@ -118376,6 +118438,42 @@ Commands:
   workspace Shared Agent Context: workspaces, FWK reads, propose/review (module sac)
   retention Bound stores that grow without bound (gdctx raw/artifacts, owner write-conflict sidecars)
   forgetting Read the deletion trail \u2014 was this removed, or did it never exist?
+`;
+function printHelp25() {
+  console.log(`keryx ${VERSION2}
+
+${USAGE_BODY}`);
+}
+function helpRequestedFor(rest) {
+  const separator = rest.indexOf("--");
+  const head = separator === -1 ? rest : rest.slice(0, separator);
+  return head.some((token) => token === "--help" || token === "-h");
+}
+var DEEP_HELP_GROUPS = new Set(["agents", "shell"]);
+function shouldInterceptHelp(command, rest) {
+  return !DEEP_HELP_GROUPS.has(command) && helpRequestedFor(rest);
+}
+function groupUsage(command, usage = USAGE_BODY) {
+  const lines = usage.split(`
+`);
+  const startsGroup = new RegExp(`^ {2,}keryx ${command}(?:\\s|$)`);
+  const isContinuation = /^ {4,}\S/;
+  const out = [];
+  for (let i = 0;i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (!startsGroup.test(line)) {
+      continue;
+    }
+    out.push(line);
+    for (let j = i + 1;j < lines.length; j += 1) {
+      const next = lines[j] ?? "";
+      if (!isContinuation.test(next) || startsGroup.test(next) || /keryx\s/.test(next)) {
+        break;
+      }
+      out.push(next);
+    }
+  }
+  return out.length === 0 ? undefined : out.join(`
 `);
 }
 function exitCodeForError(error) {
@@ -118389,6 +118487,10 @@ if (import.meta.main) {
 }
 export {
   CLI_ROUTES,
+  USAGE_BODY,
   exitCodeForError,
-  main
+  groupUsage,
+  helpRequestedFor,
+  main,
+  shouldInterceptHelp
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.145",
+  "version": "0.2.149",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/rules/core/session-plan-bridge.mdc

@@ -0,0 +1,96 @@
+---
+description: "Bridge between an orchestrator's own CLI-owned plan and the session execution plan the operator watches in the sidebar and the /plan modal: publish the orchestrator's steps as plan items under the SAME ids, mirror every status change at the moment the orchestrator updates its own state, and use `proposed` for a plan awaiting a human. Use when a skill orchestrates multi-step work (job-orchestrator, flow-orchestrator, review-orchestrator)."
+alwaysApply: false
+---
+
+# Session Plan Bridge
+
+## Purpose
+
+An orchestrator already has a plan. `job-orchestrator` has fifteen steps in a job
+package that `keryx job status` prints; `flow-orchestrator` has tasks `T1..Tn`
+with dependencies in the Flow package; `review-orchestrator` has a fifteen-step
+checklist. Until this rule existed, every one of those plans was invisible while
+it ran: the operator saw phases announced in prose, and had to ask.
+
+The session execution plan is the surface that fixes that. It is not a second
+plan — it is a PROJECTION of the orchestrator's own plan into the one place the
+operator is already looking (the sidebar's Plan section, and `/plan` for the
+whole list). The orchestrator's own state stays the only source of truth for
+what the work is.
+
+## The mechanism, in one paragraph
+
+`plan_set` publishes the whole plan (replace-all, optimistic `expectedRevision`);
+`plan_update` moves one item (`{expectedRevision, itemId, status}`); `plan_get`
+reads it back before a write when a conflict is possible. Statuses are
+`proposed | pending | in_progress | completed | blocked | skipped`, item ids are
+stable strings, and at most one item may be `in_progress` — the mechanism refuses
+a second one. `proposed` means "published for a human to approve": it is NOT work
+in progress, so it never makes the agent continue on its own, which is what makes
+"publish the plan, then stop and wait for the operator" a real stopping point.
+
+## Item ids are the orchestrator's own ids — never invented
+
+| Orchestrator | Item ids | Where they come from |
+|---|---|---|
+| `job-orchestrator` | the step ids `keryx job status <name> --json` reports — `analyze`, `context`, `prepare`, `tests-creator`, `implement`, `sanity-check`, `verify`, `review`, `security`, `fix`, `verify-post-fix`, `perf-check`, `report`, `pr`, `deploy` | `keryx job status <name>` (read it, never retype it) |
+| `flow-orchestrator` | the Flow's task ids `T1..Tn` | `keryx flow status <id>` / the Flow's `tasks.md` |
+| `review-orchestrator` | `step-0` … `step-14`, from its own numbered checklist | its Workflow section |
+
+An id that exists only in the session plan is drift by construction: the operator
+cannot reconcile it with the CLI, and a resumed run cannot match it. If a
+conditional step never runs, it is `skipped` — never absent.
+
+## Status mapping — the vocabularies disagree, this is the translation
+
+| Orchestrator's own status | Session plan status |
+|---|---|
+| `pending` (job) | `pending` |
+| `in-progress` (job, hyphenated) | `in_progress` |
+| `completed` | `completed` |
+| `skipped` | `skipped` |
+| `failed` (job / flow task) | `blocked` — it needs a human, and the failure reason goes in the item's title |
+| `blocked` (flow task) | `blocked` |
+
+## When to publish, and when to update
+
+1. **Publish once, as soon as the plan exists** — after `job-orchestrator`'s 1.1
+   plan build, after the Flow's task list exists in Phase 1, after
+   `review-orchestrator` fixes its scope and dispatch in Step 6. Not at the end.
+2. **`proposed` for a plan that is awaiting the operator.** Where an orchestrator
+   stops to ask — `job-orchestrator` 1.3's "Proceed? (yes / adjust …)" and
+   `flow-orchestrator` Phase 4's completion choice — the items are `proposed`
+   until the answer arrives, then become `pending`/`in_progress`. This is the
+   whole point of the status: the sidebar says `◇ awaiting approval` at exactly
+   the moment the orchestrator is waiting for the human.
+3. **Mirror every status change in the same breath as your own.** The call that
+   marks a step in `keryx job step …` / `keryx flow task done …` is the call that
+   updates the session plan. A batch of `plan_update`s after the work is done is
+   not progress reporting, it is a summary.
+4. **One `in_progress`** — the step being executed right now. Progress the
+   operator can see is a moving marker, not a growing list of ticks.
+5. **`blocked` when the run needs the operator** — an approval, a credential, a
+   failure that needs a decision.
+6. **`plan_get` before a write when a conflict is possible** (a resumed session, a
+   second shell on the same checkout) and re-apply against the revision you read.
+
+## What the bridge is NOT
+
+- Not a journal. Dispatch details, subagent names, token budgets and reasoning
+  belong in `journal.md` / the job's `man/` documents, not in plan items.
+- Not authoritative. If the session plan and `keryx job status` / `keryx flow
+  status` disagree, the CLI state wins and the session plan is corrected on the
+  next update — the projection follows the plan, never the other way round.
+- Not a completion signal. A plan whose items are all `completed` does not mean
+  the job is done: verification, review and the completion report are the
+  orchestrator's own gates.
+
+## Red Flags — stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "I'll publish the plan when the work is finished and I know all the statuses" | That is a report, not a plan. The sidebar exists so the operator can watch WHILE it runs — a plan published at the end has nothing to show. |
+| "The ids are mine to choose, as long as the titles match" | Then the session plan and `keryx job status` cannot be reconciled by a human or by a resumed run, and the projection has become a second plan. |
+| "`proposed` is the same as `pending`, I'll just use `pending`" | `pending` is actionable work, so the agent continues on its own and the "wait for approval" gate disappears. |
+| "Skipping the plan is fine when the job is short" | Then the operator's single progress surface is empty for exactly the runs where watching matters most. |

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.md

@@ -32,7 +32,7 @@ Proceed directly with your assigned task.
 
 ## Purpose
 
-Performs deep cross-repository analysis to understand business logic, architecture, API contracts, and implementation requirements. Generates structured documentation for both human developers and AI agents.
+Performs deep cross-repository analysis to understand business logic, architecture, API contracts, and implementation requirements. Generates structured documentation for both human developers and AI agents. Plan bridge: publish each `Step N` this run will take with `plan_set`, and update it with `plan_update` as it finishes — see the `session-plan-bridge` rule.
 
 **Two Analysis Modes:**
 

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -28,7 +28,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 
 ## Arguments
 
-- `/feature-dev <description>` — start from a text description
+- `/feature-dev <description>` — start from a text description. Plan bridge: publish `phase-1`…`phase-8` with `plan_set`/`plan_update`; while a confirmation question is open the items are `proposed` — see the `session-plan-bridge` rule.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -23,7 +23,7 @@ license: "MIT"
 
 ## Purpose
 
-Flow Orchestrator is the Task Manager-aware implementation orchestrator.
+Flow Orchestrator is the Task Manager-aware implementation orchestrator. Plan bridge: publish the tasks with `plan_set` under the ids `T1`…`Tn`, mirror each `keryx flow task done` with `plan_update`, and publish Phase 4's completion choice as `proposed` — see the `session-plan-bridge` rule.
 It wraps the existing gdskills pipeline with `keryx flow` state.
 
 Use this skill instead of `job-orchestrator` when the user wants a managed

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.md

@@ -20,7 +20,7 @@ license: "MIT"
 
 ## Purpose
 
-Analyzes a GitHub issue and decomposes it into atomic implementation tasks that can be dispatched to `task-implementer` sub-agents. Designed to run autonomously as a sub-agent — no user interaction required.
+Analyzes a GitHub issue and decomposes it into atomic implementation tasks that can be dispatched to `task-implementer` sub-agents. Designed to run autonomously as a sub-agent — no user interaction required. Plan bridge: publish these four phases with `plan_set` under the ids `phase-1`…`phase-4` and move each with `plan_update` — see the `session-plan-bridge` rule.
 
 **Input:** GitHub issue URL (or repo + number) + codebase path(s)
 **Output:** JSON analysis object with one task entry per atomic task, each containing full context for implementation

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -32,7 +32,7 @@ Proceed directly with your assigned task.
 
 ## Purpose
 
-Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`.
+Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`. Plan bridge: publish these steps with `plan_set` under the ids `keryx job status` reports, mirror each `keryx job step` with `plan_update`, and mark them `proposed` while the approval above is open — see the `session-plan-bridge` rule.
 
 **The package is the state.** `keryx job` is the only writer of `state.json`; it validates every write against the registered contract `job-orchestrator-state` and refuses one that does not conform. Never hand-write `state.json`, and never hold a step's outcome only in this session — a step recorded nowhere is a step that did not happen as far as the next session is concerned.
 

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -27,7 +27,7 @@ metadata:
 
 ## Purpose
 
-Thin orchestrator that drives a 5-phase autonomous documentation pipeline.
+Thin orchestrator that drives a 5-phase autonomous documentation pipeline. Plan bridge: publish `phase-0`…`phase-5` with `plan_set` and `plan_update`; `state.json` stays the source of truth — see the `session-plan-bridge` rule.
 Takes an existing codebase as input, dispatches specialized subagents to scan,
 analyze, and write documentation, and produces a complete documentation package
 with no human gates.

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -34,7 +34,7 @@ When a USER runs this orchestrator directly (not as a dispatched subagent), at
 the start ask "Collect execution statistics for this run? (yes/no)" per
 `.metaproject/rules/core/execution-metrics.md`. If yes, append the
 `## Execution Metrics` section at the end and save it under the docpack output
-dir. Never ask or emit it when dispatched as a subagent.
+dir. Never ask or emit it when dispatched as a subagent. Plan bridge: publish `phase-0`…`phase-5` with `plan_set`/`plan_update`, and hold them `proposed` while Phase 0's location question is open — see the `session-plan-bridge` rule.
 
 ## Iron Laws
 

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -61,7 +61,7 @@ already hold (`--scope`, `--findings`, `--diff-lines`, `--fix-attempt`,
 `--verifier`, `--security`, `--forced-strategy-change`) and paste the `model`
 block it prints into that dispatch.
 
-Do NOT assign the tier by reading the table in `rules/core/model-selection.mdc`.
+Do NOT assign the tier by reading the table in `rules/core/model-selection.mdc`. Plan bridge: publish this checklist with `plan_set` under the ids `step-0`…`step-14` and move each item with `plan_update` as its step completes — see the `session-plan-bridge` rule.
 Working it out in your head is exactly the mechanical step that rule moves into
 code — and it is the step that was documented as running for a whole release
 while nothing called it.

package/src/gdskills/bundled/skills/review/review-pr-feedback/SKILL.md

@@ -56,7 +56,7 @@ a plan is the deliverable of analyze mode, not a preamble to one.
 
 ```
 review-pr-feedback Progress:
-- [ ] Step 1: Read job context (if CONTEXT_PATH provided)
+- [ ] Step 1: Read job context (if CONTEXT_PATH provided). Plan bridge: publish each `Step N` with `plan_set`, and move it with `plan_update` as the step completes — see the `session-plan-bridge` rule.
 - [ ] Step 2: Resolve the PR — owner, repo, number, head branch, base branch, head SHA
 - [ ] Step 3: Collect comments — `keryx review comments collect`, never by hand
 - [ ] Step 4: Group by author