harnery 0.31.2 → 0.31.4

package/dist/lib/instructions/splice.js

@@ -14,7 +14,7 @@
  *   2. A **fully-owned file** harnery creates whole (a shipped skill's
  *      `SKILL.md`), carrying an ownership header comment so `deinit` deletes
  *      only files harnery generated and `--check` flags a hand-edit:
- *        <!-- harnery:generated <name> v=<hash> — machine-owned … -->
+ *        <!-- harnery:generated <name> v=<hash>; machine-owned … -->
  *
  * Modeled on the first host's HTML-theme splicer (regenerate + byte-compare,
  * sha256-8 hash, content outside the region untouchable). Pure (no fs) so it's
@@ -103,7 +103,7 @@ export function buildOwnedSkill(opts) {
         "---",
     ].join("\n");
     const body = opts.body.trim();
-    const marker = `<!-- harnery:generated ${opts.name} v=${shortHash(body)} — machine-owned; ` +
+    const marker = `<!-- harnery:generated ${opts.name} v=${shortHash(body)}; machine-owned; ` +
         `regenerated by \`${opts.binName} init\`, removed by \`${opts.binName} deinit\`. ` +
         `Edit the harnery template, not this file. -->`;
     return `${fm}\n${marker}\n\n${body}\n`;

package/dist/lib/instructions/templates.js

@@ -115,7 +115,7 @@ surfaces prior decisions, so check for precedent before re-deciding. ${decidePoi
 function decideBody(b) {
     return `The decision docket is a persistent queue for decisions you would otherwise
 route to a human. It's built on the \`${b} decision\` engine. This skill is the
-mechanics — file, find precedent, claim, and resolve with evidence. *When* a
+mechanics: file, find precedent, claim, and resolve with evidence. *When* a
 decision needs a human at all (versus one you settle yourself) is host policy;
 if this project defines that rubric, follow it.
 
@@ -128,7 +128,7 @@ if this project defines that rubric, follow it.
 ## Capture (default)
 
 1. **Check precedent first.** \`${b} decision search "<key terms>"\`. If a resolved
-   decision already answers this, cite it — don't re-litigate.
+   decision already answers this, cite it; don't re-litigate.
 2. **File it** when the choice has a second consumer (a human will want to see it,
    or a future agent will face it again) or reversal is expensive. Skip the
    docket for pure local mechanics (a variable name, one of two equivalent idioms).
@@ -141,7 +141,7 @@ if this project defines that rubric, follow it.
 
    For a decision with real substance, write a brief to a file and pass
    \`--brief <path>\` so the reviewer sees options + evidence, not a cold prompt.
-3. **Proceed on your default.** Filing does not mean blocking — note the id in your
+3. **Proceed on your default.** Filing does not mean blocking. Note the id in your
    reply and keep working.
 
 ## Resolve (\`resolve <id>\`)
@@ -151,7 +151,7 @@ ${b} decision show <id>     # read the question + context + any brief
 ${b} decision claim <id>    # mark it deliberating (claimed by you)
 \`\`\`
 
-Research it for real — run the queries, read the files, compute the costs. Then
+Research it for real: run the queries, read the files, compute the costs. Then
 resolve with **cited evidence** (the engine rejects an evidence-free resolution):
 
 \`\`\`bash
@@ -210,7 +210,7 @@ ${b} council list --mine --json
 
 One section per council you're a member of: id + objective, round N (open /
 collected) with N/M contributors, and your status (awaiting prompt / prompt ready
-/ already contributed) with the next command to run. Stop after listing — don't
+/ already contributed) with the next command to run. Stop after listing; don't
 auto-route into contribute.
 
 ## Create (\`create <objective>\`)
@@ -224,18 +224,18 @@ http://localhost:9000/councils/new?objective=<encoded>
 
 If the dev server isn't up, start it with \`${b} web up\`.
 
-## Contribute (\`contribute <id>\`) — the guarded flow
+## Contribute (\`contribute <id>\`): the guarded flow
 
 Run these checks in order; refuse with a specific reason if any fails.
 
-1. **Membership.** If your \`whoami\` name isn't in \`manifest.members\`, refuse — the
-   router likely meant a different agent's session.
-2. **Already contributed.** If you're in \`current_round_contributors\`, refuse —
-   wait for the steward to advance the round.
+1. **Membership.** If your \`whoami\` name isn't in \`manifest.members\`, refuse.
+   The router likely meant a different agent's session.
+2. **Already contributed.** If you're in \`current_round_contributors\`, refuse.
+   Wait for the steward to advance the round.
 3. **Prompt routing.** Find your entry in \`current_round_prompts\`. If none is
    drafted for you, refuse (the steward must write one first). If the routed body
    carries a \`<!-- council-route … member: <name> -->\` header naming a *different*
-   agent, refuse — the wrong prompt was pasted into your session.
+   agent, refuse: the wrong prompt was pasted into your session.
 4. **Compose** per your prompt (read \`manifest.target_doc\` in full if set; strip
    the route header before treating the body as instructions).
 5. **Submit:**
@@ -250,20 +250,20 @@ Run these checks in order; refuse with a specific reason if any fails.
    \`<trivial>\` angle-bracket tag on the final line (the exit-criterion parser keys
    on it). When in doubt, lean \`<trivial>\`.
 
-## Prompts (\`prompts <id>\`) — steward
+## Prompts (\`prompts <id>\`): steward
 
 1. **Authority.** If your \`whoami\` name ≠ the council's \`steward\`, stop.
 2. **Plan the round** from the target doc + prior rounds. Round 1 must include a
-   completeness critic — assign one member the explicit charge: "What important
-   thing is NOT in this document at all — a missing dimension, not a flaw in what's
-   written?" Lens-scoped reviewers reliably miss whole absent dimensions.
+   completeness critic. Assign one member the explicit charge: "What important
+   thing is NOT in this document at all (a missing dimension, not a flaw in what's
+   written)?" Lens-scoped reviewers reliably miss whole absent dimensions.
 3. **Draft + write** one prompt per member missing from \`current_round_prompts\`:
 
    \`\`\`bash
    ${b} council prompt <id> agent-<Name> --message "..."   # or --file <path>
    \`\`\`
 
-   The CLI auto-prepends the \`<!-- council-route … -->\` header — never write it by
+   The CLI auto-prepends the \`<!-- council-route … -->\` header; never write it by
    hand. Every prompt must instruct the member to end with the literal
    \`<substantive>\` / \`<trivial>\` tag.
 
@@ -280,7 +280,7 @@ export const SKILLS = [
         relPath: "harn-decide/SKILL.md",
         render: (binName) => buildOwnedSkill({
             name: "harn-decide",
-            description: "File a decision into the docket instead of blocking on a human — search precedent, file it, and proceed on a reversible default; or pick up and resolve an open decision with cited evidence. Use whenever you're about to ask a human a decision-shaped question you could resolve yourself.",
+            description: "File a decision into the docket instead of blocking on a human: search precedent, file it, and proceed on a reversible default; or pick up and resolve an open decision with cited evidence. Use whenever you're about to ask a human a decision-shaped question you could resolve yourself.",
             argumentHint: "[<the decision / question you're facing> | resolve <id> | review]",
             binName,
             body: decideBody(binName),
@@ -291,7 +291,7 @@ export const SKILLS = [
         relPath: "harn-council/SKILL.md",
         render: (binName) => buildOwnedSkill({
             name: "harn-council",
-            description: "Interact with the multi-agent council system: list / create / show / prompts (steward) / contribute (member). Guards against misrouting — refuses to contribute when you aren't a member, have already contributed, or weren't routed a prompt.",
+            description: "Interact with the multi-agent council system: list / create / show / prompts (steward) / contribute (member). Guards against misrouting: refuses to contribute when you aren't a member, have already contributed, or weren't routed a prompt.",
             argumentHint: "[<id-or-fragment> | create <objective> | contribute <id> | prompts <id> | show <id>]",
             binName,
             body: councilBody(binName),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.31.2",
+  "version": "0.31.4",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/core/agents/cli.ts

@@ -164,6 +164,48 @@ async function handleProject(root: string, rest: string[]): Promise<number> {
   return 0;
 }
 
+function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "codex" {
+  if (platform === "cursor") return "cursor";
+  if (platform === "codex") return "codex";
+  return "claude-code";
+}
+
+/**
+ * Append a canonical `health.heartbeat_swept` event after an operator kill.
+ * Same envelope stale-sweep emits, so the projector's terminal / ended_at
+ * guards treat kill and sweep identically. Soft-fails: the unlink already
+ * happened.
+ */
+async function emitHeartbeatSwept(
+  root: string,
+  owner: string,
+  hb: { session_id?: string; platform?: string; last_heartbeat?: string },
+): Promise<void> {
+  try {
+    const { emit } = await import("./events/emit.ts");
+    let ageSecs: number | undefined;
+    if (hb.last_heartbeat) {
+      const ts = Date.parse(hb.last_heartbeat);
+      if (Number.isFinite(ts)) {
+        ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+      }
+    }
+    emit(root, {
+      event_type: "health.heartbeat_swept",
+      instance_id: owner,
+      session_id: hb.session_id ?? owner,
+      adapter: adapterFromPlatform(hb.platform),
+      source: "agent-coord",
+      data: {
+        reason: "killed",
+        ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}),
+      },
+    });
+  } catch {
+    /* soft-fail: never break the caller */
+  }
+}
+
 /**
  * Append a canonical `claim.release` event for a path dropped from an owner's
  * files_touched. The path is canonicalized to repo-relative (matching the
@@ -181,14 +223,11 @@ async function emitClaimRelease(
   try {
     const { emit } = await import("./events/emit.ts");
     const canonical = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
-    const platform = hb.platform;
-    const adapter =
-      platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
     emit(root, {
       event_type: "claim.release",
       instance_id: owner,
       session_id: hb.session_id ?? owner,
-      adapter,
+      adapter: adapterFromPlatform(hb.platform),
       source: "agent-coord",
       data: { path: canonical, reason },
     });
@@ -269,9 +308,17 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       // killing only the file leaves the claims resurrectable from the
       // permanent Edit/Write events on the next full replay (observed: a
       // 6-day-dead agent's claims returning after its heartbeat was killed).
+      //
+      // Also emit health.heartbeat_swept so the stream records a terminal
+      // marker. Without it, a later drain that replays [session.start …
+      // tools … claim.release] treats the owner as still in-flight and
+      // re-creates the file (kill→resurrect loop observed 2026-08-03: 21
+      // killed zombies back within a minute via claim.release seeding +
+      // historical replay).
       const before = writer.readHeartbeat(root, owner);
       const ok = writer.killHeartbeat(root, owner);
       if (ok && before) {
+        await emitHeartbeatSwept(root, owner, before);
         for (const held of before.files_touched ?? []) {
           await emitClaimRelease(root, owner, before, held, "heal");
         }

package/src/core/agents/state/heartbeat-projector.ts

@@ -65,30 +65,30 @@ export function projectHeartbeats(
 ): { written: string[]; perOwner: Record<string, V2Heartbeat> } {
   const perOwner: Record<string, V2Heartbeat> = {};
 
-  // Terminal events for an owner we've never seen must NOT seed a new heartbeat:
-  // that resurrects a dead agent as a nameless, started_at-less zombie (the
-  // `agent-unknown (20608d ago)` ghost). It happens when a subagent.stop /
-  // session.end drains without (or after) its matching start: seed() then
-  // apply(stop) writes a bare tombstone the sweep+readers then choke on. If
-  // there's no existing heartbeat and the first event we see for an owner is
-  // terminal, skip it entirely.
+  // Events that must NOT seed a heartbeat for an owner with no live file.
+  // Terminal lifecycle events (session.end / subagent.stop /
+  // health.heartbeat_swept) used to be the whole set — a stop without a
+  // matching start resurrected a nameless `agent-unknown` tombstone, and a
+  // lone health.heartbeat_swept re-created the file stale-sweep had just
+  // deleted (self-perpetuating zombie loop, same instance swept 18×).
   //
-  // `health.heartbeat_swept` is terminal for the same reason, and was the
-  // sharper bug: stale-sweep deletes a dead heartbeat then emits this event,
-  // which the projector replayed to RE-CREATE the very file the sweep just
-  // removed (minus files_touched, since no start event ever ran for it). The
-  // reader then flagged it "missing required fields", and the resurrected file,
-  // carrying a fresh last_heartbeat = the swept-event ts, survived one
-  // freshness window before the next sweep deleted-and-resurrected it again. A
-  // self-perpetuating zombie loop (same instance swept 18×). A swept event must
-  // never seed a heartbeat.
-  const TERMINAL = new Set(["session.end", "subagent.stop", "health.heartbeat_swept"]);
+  // `claim.release` joins them: kill-heartbeat unlinks the file THEN emits
+  // claim.release for each held path so replay honors the drop. Projecting
+  // those releases alone used to seed a fresh heartbeat (name recovered from
+  // .name-history, last_heartbeat = release ts), undoing the kill. Side-effect
+  // events must never birth an owner.
+  const NEVER_SEED = new Set([
+    "session.end",
+    "subagent.stop",
+    "health.heartbeat_swept",
+    "claim.release",
+  ]);
 
   // Seed from any existing v2 files so a partial replay doesn't reset state.
   for (const ev of events) {
     if (!perOwner[ev.instance_id]) {
       const existing = readExisting(coordRoot, ev.instance_id);
-      if (!existing && TERMINAL.has(ev.event_type)) continue;
+      if (!existing && NEVER_SEED.has(ev.event_type)) continue;
       perOwner[ev.instance_id] = existing ?? seed(ev, coordRoot);
     }
     apply(perOwner[ev.instance_id]!, ev, coordRoot);
@@ -158,7 +158,20 @@ function seed(ev: CanonicalEvent, coordRoot: string): V2Heartbeat {
 }
 
 function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
-  hb.last_heartbeat = ev.ts;
+  // Sweep telemetry must not refresh liveness. apply() used to stamp
+  // last_heartbeat = ev.ts for every event, so a drain that replayed
+  // [session.start … tools … health.heartbeat_swept] wrote a heartbeat whose
+  // last_heartbeat was the swept ts — looking freshly alive for another
+  // freshness window, which the next sweep deleted-and-re-emitted. Record the
+  // event for audit (last_event_id / events_applied) but keep the prior
+  // liveness stamp; also set ended_at so the mid-batch write guard skips
+  // re-creating a file the sweep/kill already removed.
+  const isSweepTelemetry = ev.event_type === "health.heartbeat_swept";
+  if (!isSweepTelemetry) {
+    hb.last_heartbeat = ev.ts;
+  } else if (!hb.last_heartbeat) {
+    hb.last_heartbeat = ev.ts;
+  }
   hb.last_event_id = ev.event_id;
   hb.events_applied += 1;
   hb.v2_meta.last_projected = new Date().toISOString();
@@ -201,6 +214,10 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       hb.clean_exit = pickBool(d, "clean_exit");
       break;
 
+    case "health.heartbeat_swept":
+      hb.ended_at = ev.ts;
+      break;
+
     case "subagent.start": {
       const name = pickStr(d, "name");
       if (name) hb.name = name;

package/src/core/agents/state/heartbeat-writer.ts

@@ -347,6 +347,61 @@ export function healHeartbeat(
   return hb;
 }
 
+/**
+ * Register a workflow child in the coordination layer from the ENGINE side.
+ *
+ * Previously a spawned child was visible only if its adapter fired Harnery's
+ * hooks, which made coordination visibility a property of the vendor CLI
+ * rather than of the engine. Headless `codex exec` fires no hooks, so codex
+ * children never appeared in `harn agents list` and rendered as "no live
+ * session" on the run page while actively working — for the entire length of
+ * a multi-minute stage.
+ *
+ * The engine already knows every fact a heartbeat needs at spawn time, so it
+ * writes one itself. Hook-firing adapters keep enriching the same file
+ * (last_tool, files_touched); non-hook adapters at least become visible and
+ * attributable. Pair with `killHeartbeat` when the child ends.
+ *
+ * Idempotent: re-registering refreshes in place and preserves `started_at`
+ * and any claims a hook already recorded.
+ */
+export function registerWorkflowChild(
+  coordRoot: string,
+  opts: {
+    instanceId: string;
+    runId: string;
+    agentId: string;
+    sessionId?: string;
+    adapter?: string;
+    label?: string;
+    model?: string;
+  },
+): Heartbeat {
+  const now = nowIsoSeconds();
+  const prior = readHeartbeat(coordRoot, opts.instanceId);
+  const hb: Heartbeat = {
+    ...(prior ?? {}),
+    schema_version: 1,
+    instance_id: opts.instanceId,
+    // The reader keys children by session_id and skips any heartbeat missing
+    // one, so it must always be set even before the adapter mints a real id.
+    session_id: prior?.session_id ?? opts.sessionId ?? opts.instanceId,
+    name: opts.label || opts.agentId,
+    kind: "workflow-child",
+    agent_id: opts.agentId,
+    model: opts.model ?? prior?.model ?? "",
+    platform: adapterToPlatform(opts.adapter),
+    started_at: prior?.started_at ?? now,
+    last_heartbeat: now,
+    files_touched: prior?.files_touched ?? [],
+    task: opts.label ?? "",
+    workflow_run_id: opts.runId,
+    workflow_agent_id: opts.agentId,
+  };
+  atomicWrite(heartbeatPath(coordRoot, opts.instanceId), JSON.stringify(hb, null, 2));
+  return hb;
+}
+
 /**
  * Stamp the heartbeat with the most-recent tool name + target. Written from
  * the post-tool-use hook.

package/src/core/hooks/events/schema.ts

@@ -419,18 +419,19 @@ export type HealthPidmapHeal = EventEnvelope<
 >;
 
 /**
- * A heartbeat file was removed by stale-sweep. Symmetric with
- * `health.heartbeat_heal` so the full lifecycle (created → healed → swept) is
- * auditable from the event stream alone. Sweeps were silent before, which
- * made "why did this agent vanish?" un-answerable without guesswork.
+ * A heartbeat file was removed by stale-sweep or an operator kill. Symmetric
+ * with `health.heartbeat_heal` so the full lifecycle (created → healed →
+ * swept) is auditable from the event stream alone. Sweeps were silent before,
+ * which made "why did this agent vanish?" un-answerable without guesswork.
  * `reason`: "stale" (last_heartbeat past the freshness cutoff) | "unparseable"
  * (JSON.parse failed AND mtime was old) | "missing_ts" (no last_heartbeat AND
- * mtime was old). Fresh-mtime files are never swept regardless of content.
+ * mtime was old) | "killed" (operator `kill-heartbeat` / `agents heal --kind
+ * kill`). Fresh-mtime files are never auto-swept regardless of content.
  */
 export type HealthHeartbeatSwept = EventEnvelope<
   "health.heartbeat_swept",
   {
-    reason: "stale" | "unparseable" | "missing_ts";
+    reason: "stale" | "unparseable" | "missing_ts" | "killed";
     age_secs?: number;
   }
 >;

package/src/core/workflow/engine.ts

@@ -21,6 +21,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { killHeartbeat, registerWorkflowChild } from "../agents/state/heartbeat-writer.ts";
 import { snapshotRepo } from "../context/index.ts";
 import type {
   ExternalMutationRequest,
@@ -109,6 +110,17 @@ const DEFAULT_MAX_AGENTS = 50;
 const DEFAULT_CONCURRENCY = 4;
 const DEFAULT_MAX_ATTEMPTS = 2;
 const DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * Deterministic coordination identity for a spawned child.
+ *
+ * Stable per (run, agent) so a re-register refreshes one heartbeat instead of
+ * accumulating duplicates, and so an orphan left by a killed engine is
+ * greppable straight back to the run that owned it.
+ */
+function childInstanceId(runId: string, agentId: string): string {
+  return `${runId}-${agentId}`;
+}
 const DEFAULT_MAX_TURNS = 25;
 const DEFAULT_POLICY_ASK_TIMEOUT_MS = 60_000;
 const MAX_POLICY_DECISIONS = 50;
@@ -935,6 +947,24 @@ async function executeWorkflow(
       });
       log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${adapter}] ${label}`);
 
+      // Register the child ourselves rather than trusting its adapter to fire
+      // Harnery's hooks. Headless `codex exec` fires none, so codex children
+      // were invisible to `harn agents list` and the run page for the whole
+      // duration of a stage. The engine knows everything the heartbeat needs.
+      // Best-effort: coordination visibility must never fail a run.
+      try {
+        registerWorkflowChild(opts.coordRoot, {
+          instanceId: childInstanceId(runId, id),
+          runId,
+          agentId: id,
+          adapter,
+          label,
+          model: agentOpts.model,
+        });
+      } catch {
+        /* visibility is not worth failing a spawn over */
+      }
+
       let attemptPrompt = dispatchPrompt;
       let last: SpawnResult | null = null;
       let agentCostUsd = 0;
@@ -1047,6 +1077,14 @@ async function executeWorkflow(
       throw error;
     } finally {
       reservedCostUsd = Math.max(0, reservedCostUsd - reservedForDispatch);
+      // Deregister on every exit path, including throw. A child heartbeat that
+      // outlives its process reads as a live agent forever and blocks peers on
+      // its stale claims. The transcript remains the durable record.
+      try {
+        killHeartbeat(opts.coordRoot, childInstanceId(runId, id));
+      } catch {
+        /* already gone, or swept */
+      }
       release();
     }
   };

package/src/core/workflow/proof.ts

@@ -173,7 +173,12 @@ export function createEvidenceRecord(input: {
     recorded_at: input.recordedAt ?? new Date().toISOString(),
     kind: enumValue(value.kind, EVIDENCE_KINDS, "evidence kind"),
     status: enumValue(value.status, ["passed", "failed", "observed", "unknown"], "evidence status"),
-    label: boundedRequired(value.label, "evidence label", MAX_LABEL_CHARS),
+    // Truncate rather than throw. A label is a display string; the substance
+    // lives in `summary` and `ref`. Throwing here discards the whole run at
+    // the point evidence is recorded, which is the END of the work — a real
+    // three-agent review was lost because its label ran 31 characters long.
+    // Same posture the transcript writer already takes: shrink and say so.
+    label: truncatedRequired(value.label, "evidence label", MAX_LABEL_CHARS),
     summary: boundedOptional(value.summary, "evidence summary", MAX_SUMMARY_CHARS),
     ref: boundedOptional(value.ref, "evidence ref", MAX_REF_CHARS),
     stage: boundedOptional(input.stage, "evidence stage", MAX_LABEL_CHARS),
@@ -584,6 +589,23 @@ function boundedRequired(value: unknown, field: string, max: number): string {
   return normalized;
 }
 
+/**
+ * Like `boundedRequired`, but shortens an over-long value instead of throwing.
+ *
+ * For fields where the string is a display label rather than load-bearing
+ * content: losing the tail of a label is trivial, losing the run that produced
+ * it is not. The marker keeps the truncation visible so a reader never mistakes
+ * a shortened label for the whole thing. Still throws when the value is missing
+ * or blank — that is a caller bug, not an overflow.
+ */
+function truncatedRequired(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${field} is required`);
+  const normalized = value.trim();
+  if (normalized.length <= max) return normalized;
+  const marker = "…[truncated]";
+  return `${normalized.slice(0, Math.max(0, max - marker.length))}${marker}`;
+}
+
 function boundedOptional(value: unknown, field: string, max: number): string | undefined {
   if (value === undefined) return undefined;
   if (typeof value !== "string") throw new Error(`${field} must be a string`);

package/src/lib/browser/client.ts

@@ -81,6 +81,12 @@ export interface BrowserOptions {
   viewport?: { width: number; height: number };
   /** Default navigation timeout in ms. Default 30000. */
   navigationTimeout?: number;
+  /**
+   * Max ms to wait for Chromium to start (`launchPersistentContext` timeout).
+   * When unset, Playwright's default (30s) applies. Tests that need a faster
+   * fail→retry loop should set this explicitly (e.g. 10_000).
+   */
+  launchTimeout?: number;
   /**
    * `wait_until` strategy for `navigate`. Default `"load"`.
    * Use `"domcontentloaded"` for sites with long-running analytics scripts
@@ -213,6 +219,7 @@ export class Browser {
       this.context = await chromium.launchPersistentContext(this.profileDir, {
         headless: !this.opts.headed,
         viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+        ...(this.opts.launchTimeout !== undefined ? { timeout: this.opts.launchTimeout } : {}),
         ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
           ? { args: this.opts.launchArgs }
           : {}),

package/src/lib/instructions/splice.ts

@@ -14,7 +14,7 @@
  *   2. A **fully-owned file** harnery creates whole (a shipped skill's
  *      `SKILL.md`), carrying an ownership header comment so `deinit` deletes
  *      only files harnery generated and `--check` flags a hand-edit:
- *        <!-- harnery:generated <name> v=<hash> — machine-owned … -->
+ *        <!-- harnery:generated <name> v=<hash>; machine-owned … -->
  *
  * Modeled on the first host's HTML-theme splicer (regenerate + byte-compare,
  * sha256-8 hash, content outside the region untouchable). Pure (no fs) so it's
@@ -133,7 +133,7 @@ export function buildOwnedSkill(opts: {
   ].join("\n");
   const body = opts.body.trim();
   const marker =
-    `<!-- harnery:generated ${opts.name} v=${shortHash(body)} — machine-owned; ` +
+    `<!-- harnery:generated ${opts.name} v=${shortHash(body)}; machine-owned; ` +
     `regenerated by \`${opts.binName} init\`, removed by \`${opts.binName} deinit\`. ` +
     `Edit the harnery template, not this file. -->`;
   return `${fm}\n${marker}\n\n${body}\n`;