harnery 0.41.0 → 0.43.0

package/dist/lib/tunnel/state.js

@@ -1,12 +1,25 @@
 // Tunnel config + state persistence + provider helpers. Commands default to
 // <cwd>/.cache/tunnel/; gitignored, so the allowlist is per-machine.
-import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
-import { resolve } from "node:path";
-// Tunnel state lives under <root>/.cache/tunnel/. Root defaults to cwd for the
-// command surface and can be supplied by callers that already resolved a repo.
-function cachePath(tool, filename, root = process.cwd()) {
-    const dir = resolve(root, ".cache", tool);
+import { spawnSync } from "node:child_process";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { isPathAllowed } from "./path-scope.js";
+/** Overrides the directory that holds tunnel state and config (a host keeps it out of `.cache/`). */
+export const TUNNEL_DIR_ENV = "HARNERY_TUNNEL_DIR";
+/** Explicit cloudflared binary, for a host that ships a managed copy. */
+export const CLOUDFLARED_ENV = "HARNERY_CLOUDFLARED";
+/**
+ * Where tunnel state lives: `$HARNERY_TUNNEL_DIR` when set, else
+ * `<root>/.cache/tunnel/`. Root defaults to cwd for the command surface and can
+ * be supplied by callers that already resolved a repo.
+ */
+export function tunnelDir(root = process.cwd(), env = process.env) {
+    const override = env[TUNNEL_DIR_ENV]?.trim();
+    return override ? resolve(override) : resolve(root, ".cache", "tunnel");
+}
+function cachePath(filename, root = process.cwd()) {
+    const dir = tunnelDir(root);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     return resolve(dir, filename);
@@ -46,28 +59,41 @@ function nameFromStateFile(file) {
 const DEFAULT_CONFIG = {
     allowed_ips: [],
 };
-/** Normalize a parsed state blob; supply `name` for pre-multi-instance files. */
+/**
+ * Normalize a parsed state blob; supply `name` for pre-multi-instance files.
+ * A state written before path scopes existed reads as an empty scope, which
+ * the gate treats as "refuse every path".
+ */
 function normalizeState(raw, fallbackName) {
-    return { ...raw, name: raw.name ?? fallbackName, provider: raw.provider ?? "cloudflare" };
+    return {
+        ...raw,
+        name: raw.name ?? fallbackName,
+        provider: raw.provider ?? "cloudflare",
+        allow_paths: Array.isArray(raw.allow_paths) ? raw.allow_paths : [],
+    };
 }
 export function readConfig() {
-    const p = cachePath("tunnel", CONFIG_FILE);
+    const p = cachePath(CONFIG_FILE);
     if (!existsSync(p)) {
         writeConfig(DEFAULT_CONFIG);
         return { ...DEFAULT_CONFIG, allowed_ips: [...DEFAULT_CONFIG.allowed_ips] };
     }
     try {
-        return JSON.parse(readFileSync(p, "utf-8"));
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        return {
+            ...parsed,
+            allowed_ips: Array.isArray(parsed.allowed_ips) ? parsed.allowed_ips : [],
+        };
     }
     catch {
         return { ...DEFAULT_CONFIG, allowed_ips: [...DEFAULT_CONFIG.allowed_ips] };
     }
 }
 export function writeConfig(cfg) {
-    writeFileSync(cachePath("tunnel", CONFIG_FILE), JSON.stringify(cfg, null, 2));
+    writeFileSync(cachePath(CONFIG_FILE), JSON.stringify(cfg, null, 2));
 }
 export function readState(name = DEFAULT_INSTANCE, root = process.cwd()) {
-    const p = cachePath("tunnel", stateFile(name), root);
+    const p = cachePath(stateFile(name), root);
     if (!existsSync(p))
         return null;
     try {
@@ -78,10 +104,10 @@ export function readState(name = DEFAULT_INSTANCE, root = process.cwd()) {
     }
 }
 export function writeState(state, root = process.cwd()) {
-    writeFileSync(cachePath("tunnel", stateFile(state.name), root), JSON.stringify(state, null, 2));
+    writeFileSync(cachePath(stateFile(state.name), root), JSON.stringify(state, null, 2));
 }
 export function clearState(name = DEFAULT_INSTANCE, root = process.cwd()) {
-    const p = cachePath("tunnel", stateFile(name), root);
+    const p = cachePath(stateFile(name), root);
     if (existsSync(p))
         unlinkSync(p);
 }
@@ -90,7 +116,7 @@ export function clearState(name = DEFAULT_INSTANCE, root = process.cwd()) {
  * `state*.json` under `.cache/tunnel/`; tolerates missing/corrupt files.
  */
 export function listStates(root = process.cwd()) {
-    const dir = resolve(root, ".cache", "tunnel");
+    const dir = tunnelDir(root);
     if (!existsSync(dir))
         return [];
     const out = [];
@@ -122,7 +148,7 @@ export function isTunnelStateLive(state, processAlive = isProcessAlive) {
     const providerPid = state.cloudflared_pid ?? state.provider_pid;
     return typeof providerPid === "number" && processAlive(providerPid);
 }
-function tunnelTargetPort(state) {
+export function tunnelTargetPort(state) {
     const value = /^[a-z][a-z\d+.-]*:\/\//i.test(state.target)
         ? state.target
         : `http://${state.target}`;
@@ -152,26 +178,85 @@ export function findLiveTunnelForOrigin(port, vhost, root = process.cwd(), proce
         state.vhost === vhost &&
         isTunnelStateLive(state, processAlive)) ?? null);
 }
-/**
- * Ensure cloudflared is on PATH or installed at ~/.local/bin/cloudflared.
- * Auto-downloads on Linux; throws on other platforms with brew hint.
- */
-export function ensureCloudflared() {
+/** True when the tunnel's path scope forwards every one of `paths`. */
+export function tunnelServesPaths(state, paths) {
+    return paths.every((path) => isPathAllowed(path, state.allow_paths));
+}
+function isRunnableFile(path) {
     try {
-        execSync("command -v cloudflared", { stdio: "ignore" });
-        return "cloudflared";
+        if (!statSync(path).isFile())
+            return false;
+        if (process.platform === "win32")
+            return true;
+        accessSync(path, constants.X_OK);
+        return true;
     }
     catch {
-        /* not on PATH; fall through */
+        return false;
+    }
+}
+/** First `name` on PATH (honoring `.exe` on Windows), or null. Needs no shell. */
+function findOnPath(name, env = process.env) {
+    const names = process.platform === "win32" ? [`${name}.exe`, name] : [name];
+    for (const dir of (env.PATH ?? env.Path ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const candidate of names) {
+            const full = join(dir, candidate);
+            if (isRunnableFile(full))
+                return full;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the cloudflared binary:
+ *   1. `$HARNERY_CLOUDFLARED`, then `cloudflared_path` in the tunnel config: an
+ *      explicit choice, so a missing or non-runnable file is an error, never a
+ *      silent fall-through to some other copy.
+ *   2. `cloudflared` on PATH.
+ *   3. `~/.local/bin/cloudflared`.
+ *   4. Linux x86-64 and arm64: download the latest release to (3).
+ * Elsewhere it throws with install guidance.
+ */
+export function ensureCloudflared(env = process.env, configuredPath = readConfig().cloudflared_path) {
+    const explicit = env[CLOUDFLARED_ENV]?.trim();
+    const fromConfig = configuredPath?.trim();
+    for (const [source, path] of [
+        [CLOUDFLARED_ENV, explicit],
+        ["cloudflared_path in the tunnel config", fromConfig],
+    ]) {
+        if (!path)
+            continue;
+        if (isRunnableFile(path))
+            return path;
+        throw new Error(`cloudflared is set by ${source} to ${path}, but that file is missing or not runnable.`);
     }
-    const local = `${process.env.HOME}/.local/bin/cloudflared`;
-    if (existsSync(local))
+    const onPath = findOnPath("cloudflared", env);
+    if (onPath)
+        return onPath;
+    const exe = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
+    const local = join(homedir(), ".local", "bin", exe);
+    if (isRunnableFile(local))
         return local;
-    if (process.platform !== "linux") {
-        throw new Error("cloudflared not installed. On macOS: `brew install cloudflared`. " +
+    const asset = process.platform === "linux"
+        ? { x64: "cloudflared-linux-amd64", arm64: "cloudflared-linux-arm64" }[process.arch]
+        : undefined;
+    if (!asset) {
+        throw new Error("cloudflared not installed. Install it (macOS: `brew install cloudflared`; Windows: " +
+            "`winget install Cloudflare.cloudflared`), or point `$HARNERY_CLOUDFLARED` at a binary. " +
             "On Linux it auto-installs to ~/.local/bin/cloudflared.");
     }
     process.stderr.write("Installing cloudflared to ~/.local/bin/...\n"); // lint-ok-emission: sync setup phase before structured output; pairs with the inherited stdio of the curl below
-    execSync(`curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ${local} && chmod +x ${local}`, { stdio: "inherit" });
+    mkdirSync(join(homedir(), ".local", "bin"), { recursive: true });
+    const download = spawnSync("curl", [
+        "-fsSL",
+        `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`,
+        "-o",
+        local,
+    ], { stdio: "inherit" });
+    if (download.status !== 0)
+        throw new Error("Downloading cloudflared failed; install it by hand.");
+    chmodSync(local, 0o755);
     return local;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -137,6 +137,11 @@
       "types": "./dist/core/supervisor/index.d.ts",
       "import": "./dist/core/supervisor/index.js"
     },
+    "./core/servers": {
+      "bun": "./src/core/servers/index.ts",
+      "types": "./dist/core/servers/index.d.ts",
+      "import": "./dist/core/servers/index.js"
+    },
     "./core/diagnostics": {
       "bun": "./src/core/diagnostics/index.ts",
       "types": "./dist/core/diagnostics/index.d.ts",
@@ -261,6 +266,7 @@
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
     "smoke": "node scripts/smoke-test.mjs",
+    "check:local": "node scripts/check-local.mjs",
     "docs:dev": "bun run --cwd docs dev",
     "docs:build": "bun run --cwd docs build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs",

package/schemas/config.schema.json

@@ -240,6 +240,53 @@
           "maximum": 3650,
           "default": 3,
           "description": "Retention for `harn artifacts create` when --days is absent. Env override: HARNERY_ARTIFACT_RETENTION_DAYS."
+        },
+        "auto_clean": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run the throttled artifact cleanup at session start and before new artifact work. Env override: HARNERY_ARTIFACT_AUTO_CLEAN."
+        },
+        "max_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Soft repository budget in bytes of disk use for unheld managed workspaces. Env override: HARNERY_ARTIFACT_MAX_BYTES."
+        },
+        "max_unit_bytes": {
+          "type": "integer",
+          "minimum": 16777216,
+          "maximum": 1099511627776,
+          "default": 1073741824,
+          "description": "Per-workspace ceiling in bytes of disk use; a workspace created with --big is exempt. Env override: HARNERY_ARTIFACT_MAX_UNIT_BYTES."
+        },
+        "idle_grace_hours": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8760,
+          "default": 24,
+          "description": "Hours an unexpired workspace must be idle (no file change, no owner heartbeat) before a size rule may delete it. Env override: HARNERY_ARTIFACT_IDLE_GRACE_HOURS."
+        },
+        "hold_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "default": 14,
+          "description": "Days a hold protects a workspace before it lapses unless renewed with `harn artifacts hold` (same id and reason). Env override: HARNERY_ARTIFACT_HOLD_DAYS."
+        },
+        "max_held_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Advisory budget in bytes of disk use for held workspaces. Exceeding it produces warnings; held work is never deleted. Env override: HARNERY_ARTIFACT_MAX_HELD_BYTES."
+        },
+        "min_free_bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1125899906842624,
+          "default": 21474836480,
+          "description": "Free-disk floor for the artifact store. Below it, artifact commands warn and `artifacts create --big` refuses without --allow-low-disk. 0 disables the floor. Env override: HARNERY_ARTIFACT_MIN_FREE_BYTES."
         }
       }
     },
@@ -306,6 +353,37 @@
           "type": "boolean",
           "default": false,
           "description": "Pin `workflow run` to subscription billing: API-key vars are scrubbed from every child env. Stamped true by `harn init` when the key is absent. Env override: HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0."
+        },
+        "workerFullAccess": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Let qualifying workflow workers launch without their vendor sandbox (ADR 0192). A launch qualifies only when this is enabled, the launching session itself can be shown to run with full access, and the worker's exact model and effort meet a floor listed here. Anything else keeps the ordinary sandboxed projection. Project config only; a user-global file cannot grant it. HARNERY_WORKFLOW_WORKER_FULL_ACCESS=0 turns it off for one process. An invalid value disables it entirely.",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "floors": {
+              "type": "object",
+              "description": "Per-adapter list of models a worker may run unsandboxed on. Keys are adapter ids.",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["model"],
+                  "properties": {
+                    "model": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Exact model id the worker must name. Aliases and the adapter's default model never match."
+                    },
+                    "minEffort": {
+                      "type": "string",
+                      "description": "Lowest qualifying effort on the adapter's declared effort scale. Required for an adapter with an effort scale; not allowed for one that encodes effort in the model id."
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -349,6 +427,19 @@
               "default": 65536
             }
           }
+        },
+        "codexWindowsBridge": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["entryPoint"],
+          "description": "Route Windows-native Codex hooks through a resident WSL bridge (decision record 0197). init writes a commandWindows on each Codex hook that calls entryPoint when it is on PATH and the working directory is a WSL path, and otherwise runs the usual command. Project config only.",
+          "properties": {
+            "entryPoint": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+              "description": "Windows command name the bridge installs, for example codex-wsl-hook. Only a bridge that implements the decision record 0197 contract should install it."
+            }
+          }
         }
       }
     },

package/src/commander.ts

@@ -280,6 +280,38 @@ export async function registerHarneryLogStorageCommands(
   return parent;
 }
 
+export interface HarneryTunnelCommandOptions {
+  emit?: EmitContext;
+  context?: HarneryProgramContext;
+}
+
+/**
+ * Mount `tunnel` under `parent`, for a host whose own program does not come
+ * from `createHarneryProgram` (a host CLI that exposes the tunnel as one of its
+ * command families).
+ */
+export async function registerHarneryTunnelCommand(
+  parent: Command,
+  options: HarneryTunnelCommandOptions = {},
+): Promise<Command> {
+  const { registerTunnelCommand } = await import("./commands/tunnel.ts");
+  registerTunnelCommand(parent, options.emit ?? defaultEmit, options.context);
+  return parent;
+}
+
+export type { RefreshCurrentOptions, RefreshCurrentResult } from "./commands/tunnel.ts";
+
+/**
+ * `tunnel allow add --current` as a function: allow this machine's public
+ * addresses and optionally reload running gates, keeping their URLs.
+ */
+export async function refreshTunnelCurrentAddress(
+  options: import("./commands/tunnel.ts").RefreshCurrentOptions,
+): Promise<import("./commands/tunnel.ts").RefreshCurrentResult> {
+  const { refreshCurrentAddress } = await import("./commands/tunnel.ts");
+  return refreshCurrentAddress(options);
+}
+
 export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   const program = new Command();
   const emit = opts.emit ?? defaultEmit;
@@ -320,6 +352,12 @@ function harneryCommandBundles({
   binName,
 }: CommandBundleContext): LazyCommandBundle[] {
   return [
+    lazy(
+      "disk [path]",
+      "Measure checkout disk usage, including nested repositories and ignored files",
+      async (program) => (await import("./commands/disk.ts")).registerDiskCommand(program, emit),
+      { hasOptions: true },
+    ),
     lazy(
       "tokens <files...>",
       "Count tokens in text/markdown files (offline, uses o200k_base as Claude proxy)",
@@ -596,6 +634,13 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/storage.ts")).registerStorageCommand(program, emit, context),
     ),
+    lazy(
+      "rm <paths...>",
+      "Preview guarded removal of untracked files; --yes applies permanent deletion",
+      async (program) =>
+        (await import("./commands/rm.ts")).registerRmCommand(program, emit, context),
+      { hasOptions: true },
+    ),
     lazy("logs", "List and query bounded Harnery log families", async (program) =>
       (await import("./commands/logs.ts")).registerLogsCommand(program, emit, context),
     ),
@@ -661,6 +706,12 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/tunnel.ts")).registerTunnelCommand(program, emit, context),
     ),
+    lazy(
+      "servers",
+      "Every local server started in this project: list, stop, clean up idle session servers, read logs",
+      async (program) =>
+        (await import("./commands/servers.ts")).registerServersCommand(program, emit, context),
+    ),
     lazy(
       "docs",
       "Documentation tooling: freshness report, metadata, lint, sweep, index",

package/src/commands/agents.ts

@@ -78,9 +78,13 @@ import {
   readHeartbeat as readHeartbeatCache,
 } from "../core/agents/state/heartbeat-writer.ts";
 import {
+  describeLiveAuthorityBlockV3,
+  liveAuthorityBlockHintV3,
+  liveAuthorityBlockV3,
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../core/agents/state/live-coordination-view.ts";
+import { forkRelationLabels, resolveForkAncestry } from "../core/agents/state/names.ts";
 import {
   type AgentActivity,
   foldSessionState,
@@ -104,6 +108,7 @@ import {
   projectCoordinationViewV3,
   readCoordinationViewV3,
 } from "../core/events/v3/coordination-view.ts";
+import { nativeInstanceIdV3 } from "../core/events/v3/live-route-observer.ts";
 import { liveInstanceIdV3 } from "../core/events/v3/live-routing.ts";
 import {
   countSummarizedSinceV3,
@@ -434,9 +439,15 @@ export function registerAgentsCommand(
       "--session-id <id>",
       "Target the heartbeat with this session_id directly, bypassing the ppid walk.",
     )
-    .action((state: string, opts: { reason?: string; sessionId?: string }) => {
-      runLifecycle(state, opts);
-    });
+    .option(
+      "--force-ancestor",
+      "Allow a fork to change its fork ancestor's lifecycle (only on explicit operator instruction)",
+    )
+    .action(
+      (state: string, opts: { reason?: string; sessionId?: string; forceAncestor?: boolean }) => {
+        runLifecycle(state, opts);
+      },
+    );
 
   cmd
     .command("end")
@@ -450,9 +461,20 @@ export function registerAgentsCommand(
       "succeeded | failed | cancelled | timed_out | denied | interrupted | unknown",
       "succeeded",
     )
-    .action((opts: { sessionId?: string; instanceId?: string; outcome: string }) => {
-      runEndSession(opts);
-    });
+    .option(
+      "--force-ancestor",
+      "Allow a fork to finalize its fork ancestor's session (only on explicit operator instruction)",
+    )
+    .action(
+      (opts: {
+        sessionId?: string;
+        instanceId?: string;
+        outcome: string;
+        forceAncestor?: boolean;
+      }) => {
+        runEndSession(opts);
+      },
+    );
 
   cmd
     .command("reconcile")
@@ -663,7 +685,40 @@ const SESSION_OUTCOMES = new Set([
   "unknown",
 ]);
 
-function runEndSession(opts: { sessionId?: string; instanceId?: string; outcome: string }) {
+/**
+ * Refuse when the calling session targets one of its recorded fork ancestors.
+ * A fork's transcript is full of its parent's name, task, and claims, so a
+ * fork that "cleans up its earlier self" is usually cutting off a live parent
+ * (2026-10-07: a fork offered to close its running parent). Returns the
+ * refusal message, or null when the call may proceed.
+ */
+function forkAncestorRefusal(
+  root: string,
+  targetIds: Array<string | undefined>,
+  force: boolean | undefined,
+  action: string,
+): string | null {
+  if (force) return null;
+  const ids = new Set(targetIds.filter((id): id is string => !!id));
+  if (ids.size === 0) return null;
+  const self = resolveOwner() ?? sessionIdentityFromEnv();
+  if (!self || ids.has(self)) return null;
+  const ancestor = resolveForkAncestry(root, self).find((a) => ids.has(a.instance_id));
+  if (!ancestor) return null;
+  const label = ancestor.name ? `agent-${ancestor.name}` : ancestor.instance_id;
+  return (
+    `${label} is this session's fork ancestor: this conversation was branched from it, so its ` +
+    `name, task, and files in your context are its own, and it may still be running. Refusing to ` +
+    `${action} it. Rerun with --force-ancestor only when the operator explicitly asked for that.`
+  );
+}
+
+function runEndSession(opts: {
+  sessionId?: string;
+  instanceId?: string;
+  outcome: string;
+  forceAncestor?: boolean;
+}) {
   const root = monorepoRoot();
   if (!root) return failCommand("not_in_repo", "not in an agent session");
   if (!SESSION_OUTCOMES.has(opts.outcome)) {
@@ -695,6 +750,15 @@ function runEndSession(opts: { sessionId?: string; instanceId?: string; outcome:
     return failCommand("session_identity_missing", "live V3 generation disappeared");
   }
   const state = record.state;
+  if (opts.instanceId || opts.sessionId) {
+    const refusal = forkAncestorRefusal(
+      root,
+      [target, state.session_id, nativeInstanceIdV3(state.instance_id)],
+      opts.forceAncestor,
+      "finalize",
+    );
+    if (refusal) return failCommand("session_is_fork_ancestor", refusal);
+  }
   if (state.delegations.length > 0) {
     return failCommand(
       "session_work_open",
@@ -1486,6 +1550,10 @@ function normalizeKind(kind: string | undefined | null): string {
  * command refuses in turn and the caller has no way to guess the path back.
  */
 function noLiveGenerationMessage(root: string, owner: string): string {
+  const block = liveAuthorityBlockV3(root, owner);
+  if (block) {
+    return `resolved owner=${owner}; ${describeLiveAuthorityBlockV3(block)}; ${liveAuthorityBlockHintV3(resolveBinName(root))}`;
+  }
   return `resolved owner=${owner} but no authority-safe live V3 generation exists for it; ${lifecycleReopenHint(root)}`;
 }
 
@@ -1985,7 +2053,10 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   });
 }
 
-function runLifecycle(rawState: string, opts: { reason?: string; sessionId?: string }): void {
+function runLifecycle(
+  rawState: string,
+  opts: { reason?: string; sessionId?: string; forceAncestor?: boolean },
+): void {
   const state = rawState.trim().toLowerCase();
   if (state !== "active" && state !== "blocked" && state !== "done") {
     emit.error({
@@ -2006,6 +2077,19 @@ function runLifecycle(rawState: string, opts: { reason?: string; sessionId?: str
     return;
   }
   if (!opts.sessionId) ensureAdapterSession(root);
+  if (opts.sessionId) {
+    const refusal = forkAncestorRefusal(
+      root,
+      [opts.sessionId],
+      opts.forceAncestor,
+      "change the lifecycle of",
+    );
+    if (refusal) {
+      emit.error({ code: "session_is_fork_ancestor", message: refusal });
+      process.exitCode = 1;
+      return;
+    }
+  }
   const myOwner = opts.sessionId ?? resolveOwner() ?? sessionIdentityFromEnv();
   if (!myOwner) {
     emit.error(
@@ -2383,8 +2467,15 @@ function runStatus(opts: {
 
   const { livePeers, stale: peersStale } = collectStatusPeerHealth(root, myOwner);
 
-  // Sort: file-holders first (by file count desc), then idle peers by recency.
+  // Recorded fork relations label the parent and forks so a fork cannot read
+  // its live parent as its own earlier session; they sort first.
+  const relations = forkRelationLabels(root, myOwner, new Set(livePeers.map((p) => p.instance_id)));
+  // Sort: related sessions, then file-holders (by file count desc), then idle
+  // peers by recency.
   livePeers.sort((a, b) => {
+    const ar = relations.has(a.instance_id) ? 1 : 0;
+    const br = relations.has(b.instance_id) ? 1 : 0;
+    if (ar !== br) return br - ar;
     const af = a.files_touched?.length ?? 0;
     const bf = b.files_touched?.length ?? 0;
     if (af !== bf) return bf - af;
@@ -2399,7 +2490,7 @@ function runStatus(opts: {
   );
   // Cross-machine presence (ADR 0016): sessions on other machines, advisory.
   const remoteMachines = readRemoteMachines(root);
-  const peersStr = formatPeers(livePeers, 4, peersStale, remoteMachines);
+  const peersStr = formatPeers(livePeers, 4, peersStale, remoteMachines, relations);
 
   const ctxUsage = readContextUsage(hb.native_session_id ?? hb.session_id, hb.platform);
   let ctxStr: string;
@@ -2593,13 +2684,15 @@ function formatPeers(
   cap: number,
   staleCount: number,
   remoteMachines: RemoteMachine[] = [],
+  relations: Map<string, string> = new Map(),
 ): string {
   if (peers.length === 0 && staleCount === 0 && remoteMachines.length === 0) return "none";
   const labels = peers.map((p) => {
     const name = p.name || "unnamed";
     const plat = formatPlatformLabel(p.platform);
     const files = p.files_touched?.length ?? 0;
-    const base = `${name} (${plat})`;
+    const relation = relations.get(p.instance_id);
+    const base = relation ? `${name} (${plat}, ${relation})` : `${name} (${plat})`;
     return files > 0 ? `${base}, ${files} files` : base;
   });
   let main: string;
@@ -5230,6 +5323,13 @@ function runHeal(opts: {
   }
 
   if (proc.status !== 0) {
+    const block = liveAuthorityBlockV3(root, owner);
+    if (block) {
+      emitHealFailure(
+        "authority_blocked",
+        `${describeLiveAuthorityBlockV3(block)}; a cache rebuild cannot restore authority the ledger withholds; ${liveAuthorityBlockHintV3(resolveBinName(root))}`,
+      );
+    }
     emitHealFailure(
       healFailureReason(root, owner, sessionId, healAdapter),
       spawnFailureMessage(proc, `agent-coord ${action}`),