@rallycry/conveyor-agent 10.13.72 → 11.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _project_shared from '@project/shared';
-import { RunnerMode, AgentSessionServiceMethods, AgentMode, PtyChatEventPayload, WorkspaceDiscoveredPort, AgentQuestion, AgentRunnerStatus } from '@project/shared';
+import { RunnerMode, AgentSessionServiceMethods, AgentMode, PtyChatEventPayload, WorkspaceDiscoveredPort, AgentQuestion, PackExecution, AgentRunnerStatus } from '@project/shared';
 export * from '@project/shared';
 import { ChildProcess } from 'node:child_process';
 
@@ -56,6 +56,31 @@ interface SpawnReviewData {
     prNumber?: number | null;
     checkoutRef?: string | null;
 }
+/**
+ * Server push asking a PLANNER pod to spawn the Builder child: a second
+ * conveyor-agent process bound to a fresh `mode:"build"` WorkspaceSession. The
+ * lifecycle handoff — a human pressing Build, or a Yolomatic plan landing —
+ * without cold-booting a second pod, and without flipping the planner's own
+ * session into a builder in place.
+ *
+ * Same wire discipline as SpawnReviewData: no taskId (the child inherits the
+ * parent's CONVEYOR_TASK_ID and the server derives it from the JWT), and the
+ * runner mode rides the JWT claim rather than this field — `mode` here is what
+ * the supervisor exports as CONVEYOR_MODE for the child process.
+ */
+interface SpawnBuilderData {
+    sessionId: string;
+    sessionJwt: string;
+    /**
+     * Runner mode for the child — `pack` when the card has children, so the
+     * coordinator gets the single-pod pack prompt and toolset. Optional so a pod
+     * running against an older server (which sends none) still boots as `task`.
+     */
+    mode?: "task" | "pack";
+    branch?: string | null;
+    /** The agent whose model/settings/instructions the Builder runs under. */
+    agentName?: string | null;
+}
 /**
  * Server push asking the builder pod to spawn an extra interactive child on
  * this pod: a second Claude TUI (mode "adhoc") or a raw login shell (mode
@@ -98,6 +123,8 @@ declare class AgentConnection {
     private earlyPullBranches;
     private spawnReviewCallback;
     private earlySpawnReviews;
+    private spawnBuilderCallback;
+    private earlySpawnBuilders;
     private spawnTuiCallback;
     private earlySpawnTuis;
     private probeUsageCallback;
@@ -168,6 +195,9 @@ declare class AgentConnection {
         branch: string;
     }) => void): void;
     onSpawnReview(callback: (data: SpawnReviewData) => void): void;
+    /** Mirror of onSpawnReview for the Builder handoff. Drains the early buffer
+     *  so a Build pressed during boot is not lost. */
+    onSpawnBuilder(callback: (data: SpawnBuilderData) => void): void;
     /**
      * Report that a same-pod review child failed to spawn (fire-and-forget).
      * The server Ends the orphaned review session and falls back to a dedicated
@@ -175,6 +205,15 @@ declare class AgentConnection {
      * it; the review session is identified separately.
      */
     reportReviewSpawnFailure(reviewSessionId: string, error?: string): void;
+    /**
+     * Report that this (planner) pod could not spawn the Builder child, so the
+     * server can End the orphaned build session and reopen the card instead of
+     * leaving it InProgress with a Builder tab that never appears.
+     *
+     * sessionId is OUR (planner) session — the task-identity guard runs on it;
+     * the build session is identified separately.
+     */
+    reportBuilderSpawnFailure(buildSessionId: string, error?: string): void;
     /**
      * Report that this pod's git credential is dead and refreshing did not fix
      * it (fire-and-forget).
@@ -412,14 +451,66 @@ declare class ModeController {
     private _pendingModeRestart;
     private _runnerMode;
     private _isAuto;
+    /**
+     * Which planner this is. Only read when `_runnerMode` is `plan`; see
+     * `effectiveMode` for the full reasoning, and `latchPlanFlavor` for why this
+     * latches toward `chat` and never away from it.
+     */
+    private _planFlavor;
     constructor(initialMode: AgentMode, runnerMode?: RunnerMode, isAuto?: boolean);
+    /**
+     * Promote this planner to the chat flavor, once, and never demote it.
+     *
+     * It cannot be a constructor-only assignment, because the constructor usually
+     * has nothing to go on. A GKE pod's bootstrap bundle carries no agentMode, so
+     * `CONVEYOR_AGENT_MODE` is unset and `initialMode` falls back to `"building"`
+     * for EVERY pod — which is the whole reason `applyServerMode` exists. Pinning
+     * the flavor at construction alone would therefore make every chat card in the
+     * cloud a discovery planner and silently re-open the defect this replaced.
+     *
+     * One-way, and both directions matter:
+     *
+     * - Only the literal card mode `chat` promotes. The server reports `chat` only
+     *   for a card whose agentMode IS `chat`, so a discovery card can never be
+     *   talked into the build-capable flavor. The original hazard — `auto` stamped
+     *   onto a plan-less auto card's planner — is untouched, because `auto` is not
+     *   `chat`.
+     * - Nothing demotes. The Build press overwrites `Task.agentMode` to
+     *   `auto`/`building` before the server sees it, so a later stamp would
+     *   otherwise strip a live conversation's prompt and file deliverables
+     *   mid-turn.
+     *
+     * The asymmetry with `auto` is principled rather than convenient: an auto
+     * card's mode and its planner phase legitimately differ, while a chat card's
+     * mode IS what its session is, for the session's whole life.
+     */
+    private latchPlanFlavor;
     get mode(): AgentMode;
     get isAuto(): boolean;
     get hasExitedPlanMode(): boolean;
     set hasExitedPlanMode(val: boolean);
     get pendingModeRestart(): boolean;
     set pendingModeRestart(val: boolean);
-    /** Effective mode accounting for PM/task defaults */
+    /**
+     * Effective mode accounting for PM/task defaults.
+     *
+     * A `plan` runner is pinned to ONE mode for its whole life, whatever the
+     * card's own agentMode later says. That pin is what makes the planner
+     * read-only, non-build-capable, and prompted for planning — all three derive
+     * from here — and it has to be immune to `applyServerMode`, which runs AFTER
+     * boot and would otherwise stamp `auto` onto the planner of a plan-less auto
+     * card, handing it the build prompt and `--dangerously-skip-permissions`
+     * inside a session whose whole purpose is not to have them.
+     *
+     * There are TWO planner flavors, and which one this session is was decided at
+     * boot (`_planFlavor`) — never re-read from the mutable `_mode`. A chat card
+     * boots a plan session too (it is a Planner-session flavor, not a builder in
+     * disguise), and it must keep `buildChatPrompt`, its file deliverables, and
+     * the build-capable tool handler. Reading the flavor from `_mode` would put
+     * that choice back under server control and re-open the exact hole the
+     * paragraph above closes, in the other direction: a stamp of `chat` onto a
+     * discovery planner would hand it build capability.
+     */
     get effectiveMode(): AgentMode;
     get isReadOnly(): boolean;
     get isAutoPlanning(): boolean;
@@ -507,7 +598,13 @@ declare class Lifecycle {
     stopGitFlush(): void;
     startUsageSample(): void;
     stopUsageSample(): void;
-    startIdleTimer(): void;
+    /** Start (or restart) the idle timer.
+     *  @param overrideMs Optional custom delay in ms, mirroring
+     *  `startDormantTimer`. SessionRunner passes a short delay when it DEFERS a
+     *  shutdown because a spawned child is still working: the pod must re-check
+     *  soon after that child exits, rather than granting itself a fresh full idle
+     *  window every time it defers. */
+    startIdleTimer(overrideMs?: number): void;
     cancelIdleTimer(): void;
     /** Start (or restart) the dormant timer.
      *  @param overrideMs Optional custom delay in ms. When provided, the timer
@@ -522,10 +619,43 @@ declare class Lifecycle {
     private clearIdleTimers;
 }
 
+/**
+ * Who else is working on this pod?
+ *
+ * The Planner is the pod's MAIN process, so its idle/dormant timeouts end the
+ * whole pod: `stopped = true` → `shutdown("finished")` → `process.exit(0)` →
+ * the supervisor logs "agent exited cleanly, shutting down pod". Nothing used
+ * to ask whether a spawned child was still working. A handed-off build that
+ * outlived the Planner's idle window therefore died mid-run — the work survived
+ * only as far as the last `conveyor-wip` flush, the janitor parked the
+ * workspace, and the card reverted to Open.
+ *
+ * This is the seam that lets `SessionRunner` ask without importing the
+ * supervisors: `cli.ts` owns them and hands the runner a probe. Keeping the
+ * dependency pointing that way also keeps the runner testable with a fake.
+ *
+ * Ordering is deliberate — `builder` first — so the deferral log names the
+ * session a human is most likely looking for when they ask why a pod is still
+ * up.
+ */
+/** A child supervisor, reduced to the one question the shutdown path asks. */
+interface ChildSessionSource {
+    /**
+     * Names the child kind in the deferral log. `tui` rather than `session` —
+     * these come from `session:spawnTui`, but "session session <id>" stutters in
+     * the one place this string is read.
+     */
+    readonly kind: "builder" | "review" | "tui";
+    /** Sessions this supervisor currently hosts. Empty when it hosts none. */
+    activeSessionIds(): string[];
+}
+
 interface SessionRunnerConfig {
     connection: AgentConnectionConfig;
     agentMode?: AgentMode;
     runnerMode?: RunnerMode;
+    /** Only read when `runnerMode` is "pack". Defaults to single-pod. */
+    packExecution?: PackExecution;
     isAuto?: boolean;
     workspaceDir: string;
     model?: string;
@@ -601,6 +731,33 @@ declare class SessionRunner {
     private agentLiveReported;
     constructor(config: SessionRunnerConfig, callbacks: SessionRunnerCallbacks, deps?: SessionRunnerDependencies);
     get state(): AgentRunnerStatus;
+    /**
+     * Supervisors whose live children keep this pod alive. Empty until `cli.ts`
+     * wires them, which is deliberate: the supervisors are constructed AFTER the
+     * runner, and an empty list simply means "no children to protect" — the
+     * pre-existing shutdown behavior.
+     */
+    private liveChildSources;
+    /** Called by `cli.ts` once the child supervisors exist. */
+    setLiveChildSources(sources: readonly ChildSessionSource[]): void;
+    /**
+     * Suppress an idle/dormant shutdown while a spawned child is still working.
+     *
+     * The Planner is the pod's main process, so its timeouts take the pod — and
+     * the Builder's in-flight work — down with it. Returns true when the shutdown
+     * was deferred and the caller must not proceed.
+     *
+     * Re-arms with a SHORT delay rather than a fresh full window: the pod should
+     * converge on shutdown soon after the last child exits, not one more idle
+     * window later. Bounded by the configured timeout so a test with a 50ms idle
+     * window re-checks in 50ms rather than a minute.
+     *
+     * Fail-open by construction — if the probe throws, or no sources are wired,
+     * the shutdown proceeds exactly as before. The opposite bias (a pod that
+     * cannot die) is the more expensive mistake here only in money; killing a
+     * live build costs work.
+     */
+    private deferShutdownForLiveChild;
     get sessionId(): string;
     get isStopped(): boolean;
     /** Wire the boot supervisor handle post-construction — cli.ts constructs it
@@ -815,6 +972,16 @@ interface AgentRunnerConfig {
     mode?: _project_shared.RunnerMode;
     isAuto?: boolean;
     agentSettings?: _project_shared.AgentSettings;
+    /**
+     * How a `mode: "pack"` session executes its children.
+     *
+     * "single-pod" (the default): this session implements every child itself,
+     * serially. "fan-out": the legacy coordinator — it fires one pod per child
+     * and writes no code. Carried as a sub-flag rather than a new `RunnerMode`
+     * so `resolveModeEnv`, the JWT mode claim, and every `mode === "pack"`
+     * reader keep working unchanged.
+     */
+    packExecution?: _project_shared.PackExecution;
 }
 interface AgentRunnerCallbacks {
     onEvent: (event: Record<string, unknown>) => void | Promise<void>;

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   SessionRunner,
   unshallowRepo
-} from "./chunk-2SN32LM6.js";
+} from "./chunk-PEEGCZAR.js";
 import "./chunk-XORJ6SII.js";
 import {
   AgentConnection,
@@ -16,8 +16,8 @@ import {
   stageAndCommit,
   updateRemoteToken,
   workspacePathExists
-} from "./chunk-LSZ2KLJY.js";
-import "./chunk-WMMBAKPE.js";
+} from "./chunk-N4WSUTGV.js";
+import "./chunk-GL2DIQEQ.js";
 import "./chunk-IA45XHOA.js";
 import {
   getWorkbenchClient

package/dist/{serve-boot-4N3FRXVQ.js → serve-boot-YPAUKENG.js}

@@ -1,6 +1,6 @@
 import {
   WorkspaceCommandSupervisor
-} from "./chunk-2L5THOWD.js";
+} from "./chunk-JQVAWRVL.js";
 import {
   AgentConnection,
   CodespacePortVisibility,
@@ -11,8 +11,8 @@ import {
   createServiceLogger,
   ensureOnTaskBranch,
   loadConveyorConfig
-} from "./chunk-LSZ2KLJY.js";
-import "./chunk-WMMBAKPE.js";
+} from "./chunk-N4WSUTGV.js";
+import "./chunk-GL2DIQEQ.js";
 import "./chunk-IA45XHOA.js";
 import "./chunk-EXQ6AHOY.js";
 import "./chunk-KMB3BU4S.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-agent",
-  "version": "10.13.72",
+  "version": "11.0.0",
   "description": "Conveyor Agent Runner v10 - PTY harness for the task chat (SDK harness for audit/project-chat). Agent-as-User architecture with BaseService patterns. Works locally too.",
   "keywords": [
     "agent",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "runtime"
+    "runtime",
+    "skills"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -36,8 +37,8 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.219",
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.246",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "node-pty": "^1.0.0",
     "socket.io-client": "^4.8.3",
     "tar": "^7.5.21",

package/skills/conveyor-build/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: conveyor-build
+description: Execute a planned Conveyor card to a pull request — one task or a whole feature-branch pack — then stay wake-able for review feedback and CI. Use when the user says "/conveyor-build <card>", "build this card", "implement this card", "run this pack", or when a claudespace session is told to follow its card's plan. Works identically in a cloud pod and in a local checkout; the card is the spec and task chat is the log. For producing the plan in the first place use conveyor-plan; to work a whole queue of Open cards use conveyor-local-loop.
+---
+
+# Conveyor Build
+
+Take a card that already has a plan and drive it to a pull request, then stay
+reachable for review feedback and CI. The card IS the spec, task chat is the
+log, and the host repo's CLAUDE.md governs gates, verification, and PR
+mechanics. This skill adds routing, claiming, and the pack chain.
+
+**One skill, two environments.** Everything below applies in a cloud pod and in
+a local checkout alike. Where they genuinely differ, the difference is called
+out in an **Environment** note — never assume; check which one you are in.
+
+## Ground rules
+
+- **Conveyor is the state store.** A build spans hours or days and the session
+  gets compacted. Re-derive state from `mcp__conveyor__get_task` +
+  `mcp__conveyor__list_subtasks` at every decision point, never from
+  conversation memory.
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__get_task`, not
+  `get_task`. Bare names fail.
+- **The card must stand alone.** If you find yourself relying on session
+  memory or on this conversation, stop and re-read the card. A plan that fails
+  the context-free-reader bar is a blocker, not something to wing: post what is
+  missing to chat and stop.
+- **Never approve or merge your own PR into `dev`.** Finish line = the card in
+  ReviewPR with CI started. The exception is narrow and lives in the pack path:
+  you ARE the reviewer of record for a pack's CHILD PRs into the pack branch,
+  because the automated reviewer skips those.
+- **Never boot another environment for work you are doing.** Locally that
+  means never `mcp__conveyor__start_task` (it exists only on the local/MCP
+  surface, and it spawns a cloud pod that duplicates you). In a pod driving a
+  pack it means never `mcp__conveyor__start_child_cloud_build` /
+  `mcp__conveyor__stop_child_build` — you implement the children yourself,
+  serially. Parallel fan-out is a deliberate choice the user makes by pressing
+  Build on the parent, not something a build session opts into.
+
+## Environment
+
+Resolve which one you are in before touching git or the filesystem.
+`mcp__conveyor__get_connection_context` answers it: a pod session reports a
+task binding and no user account.
+
+**In a pod:**
+
+- Uncommitted work is auto-snapshotted to `conveyor-wip/<branch>` after every
+  turn, so a sleep or crash does not lose the tree. Commit and push anyway as
+  soon as a chunk is coherent — committed work never depends on that mechanism.
+- `mcp__conveyor__create_pull_request` stages, commits, and pushes for you.
+- Capture UI evidence with the repo's own harness (in this repo,
+  `scripts/agent/shot.ts`) and attach with `mcp__conveyor__upload_attachment`
+  before opening the PR.
+- The database and dev server belong to this pod alone — experiment freely.
+
+**Locally:**
+
+- There is NO WIP autosync. Committed-and-pushed is the only durable state:
+  push the branch (`-u origin`) the moment it exists, and always before a long
+  background job or a wait.
+- `mcp__conveyor__create_pull_request` opens a PR for a branch you have ALREADY
+  pushed. Push first.
+- Work in the main checkout, **never a git worktree** — the provisioned
+  workspace (installed dependencies, env/direnv auth wiring, a running dev
+  stack) is the entire value of local execution, and worktrees have none of it.
+  A dirty `git status` before any branch switch is a hard stop: report and let
+  the user commit or stash. Do not solve it with a second checkout.
+- The dev database and dev-server ports are shared with the user's own
+  sessions. No destructive experiments, never reset the dev DB, and reuse a
+  running dev stack rather than fighting over ports.
+
+## Resolve and route
+
+1. Resolve the card from the argument — slug, id, or URL. **None given → ask
+   which card.** Never infer one from the branch you happen to be on.
+2. `mcp__conveyor__get_task` for the full plan and
+   `mcp__conveyor__read_task_chat` for addenda and user answers. Consult
+   `mcp__conveyor__get_tag` on the card's tags before diving in — a tag's
+   overview and linked files are the fast path into the subsystem.
+3. Route on the card's shape:
+
+| Card shape | Path |
+| --- | --- |
+| No children | **Task path** — [references/task-path.md](references/task-path.md) |
+| Has children, children PR into a **feature branch** | **Pack path** — [references/pack-path.md](references/pack-path.md) |
+| Has children that PR straight into `dev` | Not a pack chain. Build the children one at a time via the task path; leave the parent alone. |
+| Has a `parentTaskId` | Task path, but **only while the parent is parked** (neither InProgress nor ReviewPR). The child's base is the parent's feature branch, never `dev`. |
+
+> **Environment — a pod's pack runs one branch, not one branch per child.** The
+> pod's `create_pull_request` takes no task argument: it always opens the PR for
+> the card the session is bound to. A pod bound to the pack PARENT therefore
+> cannot open a CHILD's pull request, and must not try. It implements each child
+> directly on the pack branch, commits per child, moves the child's status with
+> `mcp__conveyor__update_task` (`task_id` + `status`), and opens exactly ONE pull
+> request at the end — the parent's, into `dev`.
+>
+> **Locally** each child gets its own branch and its own PR into the pack
+> branch, which is what makes them individually reviewable. Read the pack path
+> with that substitution in mind: everywhere it says "the child's PR", a pod
+> means "the child's commits on the pack branch", and the merge step becomes a
+> status write rather than a merge.
+
+**The parked-parent rule is load-bearing, not bookkeeping.** An actively
+orchestrating parent reads a headless InProgress child as a dead agent
+environment and "recovers" it onto a cloud pod — duplicate implementation of
+the same child. If the parent is InProgress or ReviewPR, decline the child and
+say why.
+
+## Claim
+
+Re-confirm the card is still claimable, then `mcp__conveyor__update_task` →
+`status: "InProgress"`, then `mcp__conveyor__post_to_chat` with a claim marker
+naming where you are running. Status changed under you → someone else took it;
+stop.
+
+**A pack parent is claimed differently** — see the pack path. The parent stays
+parked and the chat marker IS the claim.
+
+## Work the plan
+
+Post to chat at real milestones only — claim, a blocking discovery, gates
+green, PR — never play-by-play. Your turn output is not visible to the team;
+chat is.
+
+**Saving the plan and card fields:** `mcp__conveyor__update_task` handles
+title, description, plan, status, and `githubBranch` on both surfaces. Story
+points and risk are the one split: the local `update_task` carries them, the
+pod's does not — in a pod they go through
+`mcp__conveyor__update_task_properties`. Correct them when the work turns out
+materially bigger or smaller than the estimate, in either direction; a stale
+estimate is worse than a corrected one. Never re-size a card to make a gate, a
+transition, or a review pass.
+
+> **Environment — exiting plan mode in a pod.** A pod in discovery mode cannot
+> leave plan mode until the card has a plan, a title, story points, AND a risk
+> level. `update_task` carries neither of the last two, so that step needs
+> `mcp__conveyor__update_task_properties`. A pod exposes it in `discovery`,
+> `auto`, `building` and `chat` modes — but NOT in `review`, and not to a pack
+> parent. If you hold neither tool, you are not the session that is supposed to
+> be sizing the card: say so in chat rather than trying to force the transition.
+
+## Verify
+
+Follow the host repo's CLAUDE.md verification policy — scope the gates to your
+diff rather than running everything. Never open a PR with known-failing gates,
+and never silence a failure with a filter, a `.skip`, or a "known flake" note:
+either your diff broke it, or the test is broken or environment-dependent and
+you fix the test.
+
+**A UI-visible change needs visual proof before the PR**, in both environments:
+capture a screenshot (static) or a short recording (interaction) with the host
+repo's own tooling and attach it with `mcp__conveyor__upload_attachment`, then
+embed the returned URL in the PR body. A UI PR without it is incomplete.
+
+**On a deep pack the gate surface grows, and that is expected.**
+`test:affected` diffs against `origin/dev`, so by the fourth child it also
+covers the three already merged into the pack branch. That is correct
+behavior — do not go looking for why "unrelated" tests are running.
+
+> **Repo config, not an environment difference — check it, don't assume it.**
+> Where CI is configured to run only on PRs into `dev`/`main` (this is the
+> Conveyor repo's config), a child PR into a pack branch gets **no automated
+> verification at all**, and your local gate pass is the ONLY gate before that
+> child merges — mandatory, never skippable. A consumer repo may trigger CI
+> more broadly; if it does, let CI finish before merging. Confirm which case
+> you are in rather than assuming, since the two lead to opposite behavior.
+
+## Not every task ends in a PR
+
+`create_pull_request` is for work that changes code. Plenty of cards don't:
+support requests, config or credential help, answering a question,
+investigations, research whose deliverable is an answer or a file.
+
+If you finish with **no code changes** — an empty `git diff <base>..HEAD` —
+do NOT open a PR. An empty or throwaway PR exists only so a human can close it.
+Instead: post the answer, config, or findings with
+`mcp__conveyor__post_to_chat`, attach anything the user should keep with
+`mcp__conveyor__upload_attachment` (any file type, up to 25MB), and complete
+the card directly with `force_update_task_status("Complete")` — there is no PR
+or review step for a no-code task. Never publish a deliverable as an off-card
+link; the card is where it belongs.
+
+When unsure, check the diff: a real diff means open a PR, no diff means finish
+in chat and mark it Complete.
+
+## Open the PR
+
+Refresh against the card's base first, then gate, then open — in that order, so
+nothing invalidates the verification you just did:
+
+1. `git fetch origin <base> && git merge origin/<base> --no-edit`
+2. One verification pass, scoped to the diff.
+3. `mcp__conveyor__create_pull_request`, naming the base branch **explicitly**.
+   **The two surfaces spell these differently and unknown keys are silently
+   dropped, not rejected** — locally it is `head:` / `base:`; in a pod it is
+   `branch:` / `baseBranch:`. Passing the local names in a pod does not error,
+   it just leaves the base unset, and the server then falls back to the base
+   recorded on the card. That fallback is usually right and is exactly why the
+   mistake is invisible — until the card's recorded branch has drifted, and the
+   PR opens against `dev`.
+4. **Publish the PR guide** with `mcp__conveyor__publish_review_guide`, right
+   after `create_pull_request` succeeds — it is part of opening a PR, not a
+   follow-up. `sections` is a top-level array argument, not prose stuffed into
+   `overview`; keep `overview` a short intro and order the sections with core
+   behavior first, tests and generated files later. Reference only files this
+   diff actually changed, never context you merely read. Anchors are optional
+   and strict — `{"path": "..."}` alone is the safe form. Republish for the new
+   head SHA after any later push, or the card's Guide tab shows stale. It is
+   best-effort: if it still fails after one corrected retry, carry on — it
+   never blocks opening or updating the PR.
+5. Post a chat summary: what shipped, how it was verified, what a reviewer
+   should look at, and anything you did NOT do.
+
+Then confirm CI actually started (read-only `gh pr checks`). Do not wait on it.
+
+**Do not re-merge the base and do not re-run a gate that already passed.** If
+the base moved while the gates ran, open the PR anyway — CI validates against
+the merged base.
+
+## Aftercare
+
+The card is in ReviewPR. What happens next depends on who is driving:
+
+> **Environment — a pod is woken; a standalone local run is not.** In a **pod**
+> you stay wake-able: the system wakes you on CI results and review comments,
+> so go idle rather than polling. In a **standalone local run** there is no
+> wake mechanism — report the card and PR state to the user and STOP. No
+> pacing, no loop, no babysitting; a follow-up CI fix is a fresh ask. Under
+> `conveyor-local-loop` the loop's own Babysit tier owns aftercare instead, and
+> its pacing rules govern.
+
+When you are the one handling it:
+
+- **Red CI** → fix it now, on the same branch. Read the failure before
+  concluding it is yours: a suite that fails on a file your diff never touched
+  is usually environment-dependent, and the honest fix is to the test, in the
+  same PR or a dedicated one.
+- **Review comments or requested changes** → address them, then reply saying
+  what changed.
+- **Green and quiet** → leave it alone. Do not poll.
+
+## Blocked
+
+After two genuinely different failed approaches, or on a decision only the user
+can make: post the reason AND the specific question to chat, set the card back
+to `"Open"`, restore the tree (locally, `git checkout dev` — leaving a shared
+checkout parked on an abandoned feature branch is how the next session starts
+from the wrong base), and stop. A vague "this is hard" is not a handoff; the
+question is what makes it one.
+
+**A thin plan is a different case, and it does not stop a pack.** A card whose
+plan fails the context-free-reader bar: post what is missing to its chat and
+stop — but inside a pack, skip that child and take the next ready one instead
+of halting the whole chain.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.