omp-conductor 0.17.0 → 0.18.0

package/src/worker.ts

@@ -30,6 +30,77 @@ const GITHUB_PR_URL_PATTERN = /https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/
 /** `{{KEY}}` placeholders in a brief template. */
 const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
 
+/**
+ * The structured settlement a worker yields at the end of a run (#540).
+ *
+ * Fields decided here, not per project. The daemon stays the authority on
+ * green — it verifies the PR itself — so this is the worker's *claim*,
+ * cross-checked exactly as the prose report it replaces: a `green` claim
+ * must carry the PR URL and the head SHA the worker actually watched go
+ * green, and anything less fails closed.
+ */
+export interface WorkerSettlement {
+  status: "green" | "blocked" | "failed";
+  /** The run's pull request URL. Required with `status: "green"`. */
+  prUrl?: string;
+  /** The branch the PR was pushed from. */
+  branch?: string;
+  /** The 40-hex head SHA the green CI verdict was observed at. Required with `status: "green"`. */
+  headSha?: string;
+  /** What changed and why — the narrative a reviewer reads. */
+  summary: string;
+  /** What a decision or credential this run needed (blocked runs). */
+  blockers?: string[];
+  /** Commands run as evidence, exactly as executed. */
+  proof?: string[];
+}
+
+/**
+ * The JSON Schema form of {@link WorkerSettlement}, handed to the harness as
+ * the session's `outputSchema` (#540).
+ *
+ * Used two ways, and both must stay honest to the same contract:
+ * `requireYieldTool` puts the `yield` tool in front of the worker with this
+ * schema as its description, and `outputSchemaMode: "permissive"` means a
+ * violation is a fallback, never a lost report — the worker's text path must
+ * still settle a run whose yield does not parse.
+ */
+export const WORKER_SETTLEMENT_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  description:
+    "The run's settlement: what this worker claims it achieved. The daemon verifies the PR itself; " +
+    "this is the claim, cross-checked like the settlement report it replaces.",
+  additionalProperties: false,
+  required: ["status", "summary"],
+  properties: {
+    status: {
+      type: "string",
+      enum: ["green", "blocked", "failed"],
+      description:
+        "green: pushed and the checks you watched are green. blocked: a decision, credential or " +
+        "repo fact is missing. failed: the run could not complete.",
+    },
+    prUrl: { type: "string", description: "The run's pull request URL — required with status green." },
+    branch: { type: "string", description: "The branch the PR was pushed from." },
+    headSha: {
+      type: "string",
+      description: "The 40-character head SHA you observed green — required with status green.",
+    },
+    summary: { type: "string", description: "One short paragraph: what changed and why." },
+    blockers: {
+      type: "array",
+      items: { type: "string" },
+      description: "What is missing or uncertain, one item per blocker (blocked runs).",
+    },
+    proof: {
+      type: "array",
+      items: { type: "string" },
+      description: "The commands you ran as evidence, exactly as executed.",
+    },
+  },
+} as const;
+
 function scheduleWallClock(callback: () => void, delayMs: number): () => void {
   const timer = setTimeout(callback, delayMs);
   return () => clearTimeout(timer);
@@ -74,6 +145,32 @@ export const ORPHAN_RESUME_PROMPT =
   "then continue exactly where you left off: re-check the outcome of your last action before repeating it, and keep " +
   "working your original brief to the same report contract.";
 
+/**
+ * What a review-revision worker is told instead of re-sending its brief (#677).
+ *
+ * Same rule as {@link ORPHAN_RESUME_PROMPT}: the original brief is already in
+ * the resumed transcript, and re-sending it is how a resumed worker re-does
+ * work it already did. What makes this a revision rather than a resume is the
+ * deliverable contract: the PR stays open, the branch stays the run's own, and
+ * the session ends only when the same final-report shape says the revised head
+ * is green. One literal so tests can pin it.
+ */
+export const REVIEW_REVISION_PROMPT =
+  "The orchestrator reviewed your green pull request and found blocking findings. Continue this same session " +
+  "on this same run: same branch, same pull request — do not close or reopen it, and do not open another. " +
+  "Address exactly the findings below, push with conductor_push, verify the checks with conductor_pr_status, " +
+  "and finish with the same final-report contract as before (yield your settlement: status green, prUrl, headSha). " +
+  "Your original brief is already in this transcript; redo only what the findings implicate.";
+
+/**
+ * The full opening prompt for one review revision round: the pinned continuation
+ * text plus the orchestrator's findings verbatim. Exported so a unit test can
+ * pin the exact handoff without standing up a session.
+ */
+export function renderReviewRevisionPrompt(findings: string, round: number): string {
+  return `${REVIEW_REVISION_PROMPT}\n\nReview round ${round} — blocking findings:\n\n${findings}`;
+}
+
 export interface WorkerOpts {
   brief: string;
   cwd: string;
@@ -179,6 +276,13 @@ export interface WorkerResult {
   headSha?: string;
   turns: number;
   spendUsd: number;
+  /**
+   * The run's settlement text. Today this is the worker's own last words; a
+   * run that yielded a structured {@link WorkerSettlement} instead carries the
+   * canonical rendering of that parsed object (#540) — the narrative lives in
+   * its `summary`, transcribed here field for field rather than regexed out of
+   * prose.
+   */
   report: string;
   /** In-session HTTP 429 responses the session recorded (stopReason "error",
    *  errorStatus 429), counted as the messages streamed in. A healthy run
@@ -251,12 +355,34 @@ export function renderBrief(template: string, vars: Record<string, string>): str
  * must carry both a PR URL and the head SHA observed after CI; the daemon then
  * asks the tracker to verify those facts independently. Missing or malformed
  * evidence fails closed.
+ *
+ * A parsed {@link WorkerSettlement} wins over the text whenever it is present
+ * (#540): the schema is the contract now, and a misleadingly regular-looking
+ * prose block must not out-vote the object the worker actually yielded. The
+ * text path is unchanged underneath, so a run that never yields settles
+ * exactly as it did before.
  */
-export function deriveResult(report: string, repoSlug?: string): {
+export function deriveResult(
+  report: string,
+  repoSlug?: string,
+  structured?: WorkerSettlement,
+): {
   state: RunState;
   prUrl?: string;
   headSha?: string;
 } {
+  if (structured !== undefined && (structured.status === "green" || structured.status === "blocked" || structured.status === "failed")) {
+    const prUrl = structured.prUrl;
+    const headSha = structured.headSha?.toLowerCase();
+    if (structured.status === "green" && prUrl !== undefined && headSha !== undefined) {
+      return { state: "pushed-green", prUrl, headSha };
+    }
+    return {
+      state: structured.status === "blocked" ? "blocked" : "failed",
+      ...(prUrl === undefined ? {} : { prUrl }),
+      ...(headSha === undefined ? {} : { headSha }),
+    };
+  }
   const structuredPrUrl = PR_URL_PATTERN.exec(report)?.[1];
   const headSha = HEAD_SHA_PATTERN.exec(report)?.[1]?.toLowerCase();
   if (PUSHED_GREEN_PATTERN.test(report) && structuredPrUrl !== undefined && headSha !== undefined) {
@@ -279,6 +405,81 @@ export function deriveResult(report: string, repoSlug?: string): {
   };
 }
 
+/**
+ * Parse a worker's structured settlement out of one assistant message's
+ * content (#540).
+ *
+ * The worker calls the `yield` tool with `{ result: { data: <settlement> } }`
+ * and the harness records that call as a `toolCall` content block on the
+ * assistant message — the same content `reportText` flattens. Parsed
+ * permissively on purpose: `outputSchemaMode` is permissive, so a yield the
+ * schema rejected must still fall back to the text path rather than vanish.
+ * The acceptance bar mirrors the schema's own `required`: a recognizable
+ * `status` and a string `summary`; every other field is adopted when it has
+ * the right type and dropped otherwise. Exported so the run loop's precedence
+ * (yield over prose) is pinned by a unit test.
+ */
+export function structuredSettlement(content: unknown): WorkerSettlement | undefined {
+  if (!Array.isArray(content)) return undefined;
+  let parsed: WorkerSettlement | undefined;
+  for (const block of content) {
+    if (field(block, "type") !== "toolCall") continue;
+    if (field(block, "name") !== "yield") continue;
+    const args = field(block, "arguments");
+    if (args === null || typeof args !== "object") continue;
+    const result = field(args, "result");
+    if (result === null || typeof result !== "object") continue;
+    const data = field(result, "data");
+    if (data === null || typeof data !== "object" || Array.isArray(data)) continue;
+    const record = data as Record<string, unknown>;
+    const status = record.status;
+    if (status !== "green" && status !== "blocked" && status !== "failed") continue;
+    const summary = record.summary;
+    if (typeof summary !== "string") continue;
+    const settlement: WorkerSettlement = { status, summary };
+    for (const key of ["prUrl", "branch", "headSha"] as const) {
+      const value = record[key];
+      if (typeof value === "string" && value !== "") settlement[key] = value;
+    }
+    for (const key of ["blockers", "proof"] as const) {
+      const value = record[key];
+      if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        settlement[key] = value;
+      }
+    }
+    parsed = settlement;
+  }
+  return parsed;
+}
+
+/**
+ * Render a parsed {@link WorkerSettlement} as the run's stored report (#540).
+ *
+ * A worker that yields structured output may write little or no prose after
+ * the yield call, and the prose shape is no longer the contract — so the
+ * report the store keeps for such a run is this canonical rendering of the
+ * parsed object itself: the same fields a reviewer would have had to regex
+ * out of prose, derived from the object, field for field. The daemon's own
+ * postfixes — the PR-diff `changed:` line and the reliability sentence — are
+ * appended to it exactly as they are to a prose report.
+ */
+export function renderSettlement(settlement: WorkerSettlement): string {
+  const lines: string[] = [`status: ${settlement.status}`];
+  if (settlement.prUrl !== undefined) lines.push(`pr: ${settlement.prUrl}`);
+  if (settlement.branch !== undefined) lines.push(`branch: ${settlement.branch}`);
+  if (settlement.headSha !== undefined) lines.push(`head: ${settlement.headSha}`);
+  if (settlement.summary !== "") lines.push("", settlement.summary);
+  if (settlement.blockers !== undefined && settlement.blockers.length > 0) {
+    lines.push("", "blockers:");
+    for (const blocker of settlement.blockers) lines.push(`  - ${blocker}`);
+  }
+  if (settlement.proof !== undefined && settlement.proof.length > 0) {
+    lines.push("", "proof:");
+    for (const item of settlement.proof) lines.push(`  - ${item}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Did this report state a verdict at all?
  *
@@ -354,6 +555,13 @@ export async function runWorker(
       ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
       ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
       ...(o.maySpawn === undefined ? {} : { maySpawn: o.maySpawn }),
+      // The structured settlement contract (#540): the worker's `yield` tool
+      // validates its `data` payload against this schema, permissively — an
+      // invalid or absent yield falls back to the text path, never a lost
+      // report. Always-on for workers: one schema, and no per-project shape.
+      outputSchema: WORKER_SETTLEMENT_SCHEMA,
+      outputSchemaMode: "permissive",
+      requireYieldTool: true,
     });
   } catch (err) {
     // The pre-spawn gate closed (#374): a daemon stop landed while the session
@@ -447,6 +655,10 @@ export async function runWorker(
   let spendUsd = 0;
   let provider429Count = 0;
   let report = "";
+  // The newest structured settlement the worker yielded (#540). A terminal
+  // `yield` ends the run, so anything parsed here is the run's own claim, and
+  // any later message is stale-polling chatter, never a newer verdict.
+  let structured: WorkerSettlement | undefined;
   // Which model/provider actually wrote the newest assistant message. Last
   // assistant message wins: that is the durable answer even for a run that
   // never failed over (#535 slice 1, read off the message field which is where
@@ -603,15 +815,22 @@ export async function runWorker(
   session.on("message_end", (event) => {
     const message = field(event, "message");
     if (field(message, "role") !== "assistant") return;
+    const content = field(message, "content");
     // Keep the newest non-empty assistant text: whatever the worker said last
     // is its report, whether it finished cleanly or was cut off.
-    const text = reportText(field(message, "content"));
+    const text = reportText(content);
     if (text !== "") {
       report = text;
-      const stated = deriveResult(text, o.repoSlug);
-      if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
-        claim = { prUrl: stated.prUrl, headSha: stated.headSha };
-      }
+    }
+    // The structured settlement (#540): the `yield` tool call rides the same
+    // message's content as a `toolCall` block. Newest yield wins; the
+    // derivation itself prefers it over prose, so a yield and a misleadingly
+    // regular-looking text block on the same message agree in its favour.
+    const yielded = structuredSettlement(content);
+    if (yielded !== undefined) structured = yielded;
+    const stated = deriveResult(text, o.repoSlug, yielded);
+    if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
+      claim = { prUrl: stated.prUrl, headSha: stated.headSha };
     }
 
     // Real cost lives on assistant messages as `usage.cost.total` (live hermes
@@ -776,6 +995,20 @@ export async function runWorker(
     }));
   }
 
+  // A structured yield is the run's settlement: it wins over the last text —
+  // the worker may have written nothing after the yield call, and the stored
+  // report is the canonical rendering of the parsed object, not prose the
+  // regex has to recover (#540).
+  if (structured !== undefined) {
+    return withMetrics(withSessionFacts({
+      ...deriveResult(report, o.repoSlug, structured),
+      turns,
+      spendUsd,
+      provider429Count,
+      report: renderSettlement(structured),
+    }));
+  }
+
   // An explicit later verdict always wins: a worker that pushed green and then
   // stopped to ask a question means the question. The earlier claim is only
   // restored when the last thing said was not a verdict at all.

package/src/worktree.ts

@@ -759,12 +759,87 @@ export async function removeWorktree(
 
 export type RetainedWorktreeCleanup =
   | { kind: "removed" }
-  | { kind: "retained"; reason: "dirty" | "unpushed" | "unknown"; detail: string };
+  | {
+      kind: "retained";
+      reason: "dirty" | "unpushed" | "unknown" | "quarantined";
+      detail: string;
+    };
+
+/**
+ * Repairs a run repository whose `objects/info/alternates` names a path that no
+ * longer exists, re-pointing the dangling entry at this project's current
+ * mirror. Worktrees created before mirrors moved into per-project roots keep
+ * the old flat path (`<home>/mirrors/<repo>.git`); the store they borrow from
+ * is gone, so any fetch against them dies on unresolved deltas (#728). The
+ * repair belongs here — in the code that discovers the stale entry — rather
+ * than in a one-off host edit, so the next layout migration heals itself too.
+ *
+ * Only missing entries are rewritten: a valid alternate is left alone and a
+ * worktree with no alternates file is already sound. When the store cannot be
+ * made sound — the git dir is unresolvable, the file cannot be read or
+ * written, or a missing path survives the rewrite — the caller must not fetch
+ * into the broken state; a quarantine detail is returned instead.
+ */
+async function repairAlternates(
+  worktreePath: string,
+  mirrorPath: string,
+): Promise<{ kind: "ok" } | { kind: "quarantine"; detail: string }> {
+  const common = await runGit(["rev-parse", "--git-common-dir"], worktreePath);
+  if (common.code !== 0) {
+    return {
+      kind: "quarantine",
+      detail: `cannot resolve the git dir: ${common.stderr.trim() || common.stdout.trim() || "no output"}`,
+    };
+  }
+  const raw = common.stdout.trim();
+  if (raw === "") {
+    return { kind: "quarantine", detail: "cannot resolve the git dir: git printed nothing" };
+  }
+  // `--git-common-dir` is relative for linked worktrees; resolve against the
+  // tree so bare-mirror layouts and plain clones both land on the alternates.
+  const commonDir = raw.startsWith("/") ? raw : join(worktreePath, raw);
+  const alternates = join(commonDir, "objects", "info", "alternates");
+  if (!existsSync(alternates)) return { kind: "ok" };
+
+  const current = join(mirrorPath, "objects");
+  let content: string;
+  try {
+    content = readFileSync(alternates, "utf8");
+  } catch (err) {
+    return { kind: "quarantine", detail: `${alternates} cannot be read: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  let changed = false;
+  const rewritten = content.split("\n").map((line) => {
+    const candidate = line.trim();
+    if (candidate === "" || candidate === current || existsSync(candidate)) return line;
+    changed = true;
+    return current;
+  });
+  if (changed) {
+    try {
+      writeFileSync(alternates, rewritten.join("\n"));
+    } catch (err) {
+      return { kind: "quarantine", detail: `${alternates} cannot be rewritten: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  const dangling = rewritten.map((line) => line.trim()).filter((path) => path !== "" && !existsSync(path));
+  if (dangling.length > 0) {
+    return {
+      kind: "quarantine",
+      detail: `${alternates} still names missing path(s): ${dangling.join(", ")}`,
+    };
+  }
+  return { kind: "ok" };
+}
 
 /**
  * Reap a terminal run's tree and local mirror branch without deleting the only
  * copy of work. Tracker state is proved by the caller; this function proves the
- * local half after refreshing remote refs. Any ambiguity retains everything.
+ * local half after refreshing remote refs. Any ambiguity retains everything;
+ * a remote read that failed is ambiguity, never a pushed/unpushed claim, and
+ * the unpushed verdicts below are reachable only from reads that succeeded.
  */
 export async function cleanupRetainedWorktree(
   mirrorPath: string,
@@ -779,6 +854,20 @@ export async function cleanupRetainedWorktree(
 
   try {
     if (existsSync(worktreePath)) {
+      // A run repo created before mirrors moved into per-project roots may
+      // borrow objects from a path that no longer exists. Fetching into it is
+      // a guaranteed failure, so repair the alternates first — and when the
+      // store cannot be made sound, quarantine the tree instead of fetching
+      // into the broken state.
+      const repair = await repairAlternates(worktreePath, mirrorPath);
+      if (repair.kind === "quarantine") {
+        return {
+          kind: "retained",
+          reason: "quarantined",
+          detail: `worktree quarantined: ${repair.detail}`,
+        };
+      }
+
       const dirty = await git(["status", "--porcelain"], worktreePath);
       if (dirty !== "") {
         return { kind: "retained", reason: "dirty", detail: "worktree has uncommitted changes" };
@@ -794,8 +883,18 @@ export async function cleanupRetainedWorktree(
     }
 
     // A deleted remote branch can make a pushed commit look local-only until
-    // the default branch is fetched. Failure is ambiguity, never permission.
-    await git(["fetch", "--prune", "origin"], mirrorPath);
+    // the default branch is fetched. A failed fetch is ambiguity, never
+    // permission: without fresh remote refs the unpushed verdicts below are
+    // unreachable and the run is retained on an explicit unknown.
+    try {
+      await git(["fetch", "--prune", "origin"], mirrorPath);
+    } catch (err) {
+      return {
+        kind: "retained",
+        reason: "unknown",
+        detail: `remote refs could not be refreshed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
 
     const ref = `refs/heads/${branch}`;
 
@@ -806,10 +905,18 @@ export async function cleanupRetainedWorktree(
     // data loss #121 exists to prevent, reintroduced by the move to per-run
     // repositories, so it is checked where the objects actually are.
     if (existsSync(worktreePath)) {
-      await git(
-        ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
-        worktreePath,
-      );
+      try {
+        await git(
+          ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
+          worktreePath,
+        );
+      } catch (err) {
+        return {
+          kind: "retained",
+          reason: "unknown",
+          detail: `the run repository's remote refs could not be read: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
       const runUnique = await git(["rev-list", ref, "--not", "--remotes"], worktreePath);
       if (runUnique !== "") {
         return {

package/systemd/omp-conductor-recover.sh

@@ -84,6 +84,10 @@ JOURNAL_LINES=${RECOVER_JOURNAL_LINES:-200}
 VERIFY_POLL_S=${RECOVER_VERIFY_POLL_S:-2}
 VERIFY_TRIES=${RECOVER_VERIFY_TRIES:-10}
 PROJECT=${RECOVER_PROJECT:-}
+# The bound on the post-restore re-arm. `arm` with a claim-only proof performs
+# no Telegram send or wait, so it completes in milliseconds; the timeout exists
+# so a misbehaving conductor can never hang this bounded playbook (#613).
+ARM_TIMEOUT_S=${RECOVER_ARM_TIMEOUT_S:-30}
 
 # --------------------------------------------------------------------------
 # output
@@ -298,6 +302,55 @@ choose_action() { # <failed-unit>
   printf 'NONE|\n'
 }
 
+# --------------------------------------------------------------------------
+# re-arm — the one follow-on after a successful restoration (#613)
+# --------------------------------------------------------------------------
+
+# Whether the scoped project opted into claim-only arming. The unit renders
+# RECOVER_PROJECT only for an unambiguous single-project host (#510/#530), and
+# "proof" is a value unique to the project's "arm" block, so two exact-key
+# greps decide it on the machine-written config. Any unreadable, hand-formatted
+# or legacy shape (no "arm" key at all) reads as challenge — the explicit human
+# gate — which is the fail-safe direction: recovery never arms a project that
+# did not opt into claim-only.
+project_arms_claim_only() { # <config-path>
+  local path=${1:-$CONFIG_PATH}
+  [[ -f $path ]] || return 1
+  grep -qE '"arm"[[:space:]]*:' "$path" || return 1
+  grep -qE '"proof"[[:space:]]*:[[:space:]]*"claim-only"' "$path"
+}
+
+# Re-arm the scoped project through the ordinary `arm` path, unattended only
+# when the project opted into claim-only proof: that proof performs no Telegram
+# send or wait, so the command completes headless. A challenge project is never
+# poked — its gate is a human answering the challenge — and the caller's
+# escalation says so plainly instead. Prints exactly one outcome line (the
+# progress line goes to stderr, so the captured return value is the outcome).
+rearm_if_claim_only() {
+  if [[ -z $PROJECT ]]; then
+    printf 'no scoped project (RECOVER_PROJECT unset) — nothing to re-arm\n'
+    return 0
+  fi
+  if ! project_arms_claim_only "$CONFIG_PATH"; then
+    printf 'project %s keeps the challenge proof — arming stays an explicit human gate\n' "$PROJECT"
+    return 0
+  fi
+  log "re-arming $PROJECT via the ordinary arm path (claim-only proof)"
+  if dry_run; then
+    printf 'dry run: would run %s arm --project %s (claim-only, bounded by %ss)\n' "$CONDUCTOR" "$PROJECT" "$ARM_TIMEOUT_S"
+    return 0
+  fi
+  local out code
+  out=$(timeout "$ARM_TIMEOUT_S" "$CONDUCTOR" arm --project "$PROJECT" 2>&1)
+  code=$?
+  if (( code == 0 )); then
+    printf 're-armed %s via the claim-only proof\n' "$PROJECT"
+    return 0
+  fi
+  printf 're-arm of %s failed (exit %s): %s\n' "$PROJECT" "$code" "$out"
+  return 0
+}
+
 # --------------------------------------------------------------------------
 # main
 # --------------------------------------------------------------------------
@@ -318,6 +371,13 @@ run_recovery() {
       IFS='|' read -r action_name action_arg <<<"$(choose_action "$failed")"
       say "plan: failed unit $failed; action: $action_name"
     fi
+    if [[ -z $PROJECT ]]; then
+      say "plan: re-arm — none (RECOVER_PROJECT unset)"
+    elif project_arms_claim_only "$CONFIG_PATH"; then
+      say "plan: re-arm — $CONDUCTOR arm --project $PROJECT (claim-only proof, bounded by ${ARM_TIMEOUT_S}s)"
+    else
+      say "plan: re-arm — none ($PROJECT keeps the challenge proof; arming is an explicit human gate)"
+    fi
     say "plan: escalation — $(escalation_text "$failed" "${action_name:-none}" "dry run" "DRY-RUN")"
     return 0
   fi
@@ -411,6 +471,19 @@ run_recovery() {
     bump_failed_attempts
   fi
 
+  # The one follow-on a verified restoration earns (#613): re-arm the scoped
+  # project through the ordinary `arm` command. Claim-only completes headless;
+  # a challenge project stays an explicit human gate and the escalation below
+  # says so plainly. Only after `verify` passed — writing an arm marker for a
+  # fleet that is still down is the improvisation this playbook never does.
+  local rearm_line="not attempted (recovery did not verify the fleet restored)"
+  if (( ok == 0 )); then
+    rearm_line=$(rearm_if_claim_only)
+  fi
+  say "re-arm: $rearm_line"
+  append_evidence "$ev" "re-arm: $rearm_line"
+  outcome="$outcome; re-arm: $rearm_line"
+
   if escalate "$failed" "$action_name" "$outcome" "$ev"; then
     if (( ok == 0 )); then
       return 0

package/systemd/recover-unit-test.sh

@@ -97,6 +97,9 @@ case "$1" in
   --version)
     echo "0.15.11"
     ;;
+  arm)
+    echo "armed demo via fixture"
+    ;;
   report)
     echo "report 485-abc queued for demo (tier2)"
     ;;
@@ -147,6 +150,12 @@ marker() { # <case-dir> -> attempts count or 0
   fi
 }
 
+# The minimal machine-written config shape the re-arm decision greps: the arm
+# block with the chosen proof, as `saveConfig` would write it.
+write_project_config() { # <case-dir> <proof>
+  printf '{\n  "version": 2,\n  "projects": [\n    { "name": "demo", "arm": { "proof": "%s" } }\n  ]\n}\n' "$2" >"$1/state/config.json"
+}
+
 run_recover() { # <case-dir> [env assignments…]
   local d="$1"
   shift
@@ -300,6 +309,58 @@ check 'ROLLBACK escalates as well' \
 check 'the pre-upgrade snapshot survives the rollback for the operator' \
   '{"preUpgrade":true}' "$(cat "$d/state/backups/config"/config.json.pre-upgrade-*)"
 
+# ---------------------------------------------------------------------------
+# case — the post-restore re-arm (#613): a verified restoration re-arms a
+# claim-only project through the ordinary arm command; a challenge project is
+# never poked and the escalation says the human gate is explicit.
+# ---------------------------------------------------------------------------
+
+d=$(newcase rearm-claim-only)
+write_project_config "$d" claim-only
+unit_state "$d" herdr-fleet.service failed
+unit_state "$d" omp-conductor.service active
+code=$(run_with_heal "$d" herdr-fleet.service)
+check 'claim-only re-arm exits 0 when the unit heals' '0' "$code"
+check 'claim-only recovery re-arms via the ordinary arm path' \
+  'omp-conductor arm --project demo' "$(grep '^omp-conductor arm' "$d/calls")"
+check 'the escalation names the claim-only re-arm' \
+  're-armed demo via the claim-only proof' "$(grep '^omp-conductor report' "$d/calls" | head -n 1)"
+check 'the evidence bundle records the re-arm' \
+  're-arm: re-armed demo via the claim-only proof' "$(cat "$d/state/recovery"/evidence-*)"
+
+d=$(newcase rearm-challenge)
+write_project_config "$d" challenge
+unit_state "$d" herdr-fleet.service failed
+unit_state "$d" omp-conductor.service active
+code=$(run_with_heal "$d" herdr-fleet.service)
+check 'a challenge project exits 0 when the unit heals' '0' "$code"
+check 'a challenge project is never poked with arm' \
+  '' "$(grep '^omp-conductor arm' "$d/calls" || true)"
+check 'the escalation says the challenge gate is explicit' \
+  'arming stays an explicit human gate' "$(grep '^omp-conductor report' "$d/calls" | head -n 1)"
+
+# A project whose config predates the key reads as challenge: no "arm" block.
+d=$(newcase rearm-legacy-config)
+unit_state "$d" herdr-fleet.service failed
+unit_state "$d" omp-conductor.service active
+code=$(run_with_heal "$d" herdr-fleet.service)
+check 'a legacy config without arm.proof is never poked with arm' \
+  '' "$(grep '^omp-conductor arm' "$d/calls" || true)"
+check 'a legacy config keeps the human gate in the escalation' \
+  'arming stays an explicit human gate' "$(grep '^omp-conductor report' "$d/calls" | head -n 1)"
+
+# RESTART_PEER never verifies a restoration, so even a claim-only project must
+# not be re-armed while the daemon is still down.
+d=$(newcase rearm-unverified)
+write_project_config "$d" claim-only
+unit_state "$d" omp-conductor.service failed
+unit_state "$d" herdr-fleet.service active
+code=$(run_recover "$d")
+check 'an unverified recovery never re-arms' \
+  're-arm: not attempted' "$(grep 're-arm:' "$d/out" | head -n 1)"
+check 'an unverified recovery calls no arm' \
+  '' "$(grep '^omp-conductor arm' "$d/calls" || true)"
+
 # ---------------------------------------------------------------------------
 # case RESTART_PEER and the bound: attempts cap at two, then escalate-only.
 # A daemon crash with no upgrade evidence must never get a blind daemon start.