harnery 0.31.6 → 0.33.0

package/dist/commands/docs.js

@@ -1,6 +1,7 @@
 import { initDocsContext as initDocs, scanDocs } from "../lib/docs.js";
 import { initDocsMigrationContext, runFrontmatterMigration, } from "../lib/docs-frontmatter-migrate.js";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.js";
+import { initDocsContext as initDocsLinks, runLinks } from "../lib/docs-links.js";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.js";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.js";
 import { countColdHandoffs, initDocsContext as initDocsSweep, runSweep, } from "../lib/docs-sweep.js";
@@ -17,6 +18,7 @@ function ensureContext(context) {
         extraExcludedPrefixes: context.extraDocsExcludedPrefixes,
         docsRootAllowlist: context.docsRootAllowlist,
     });
+    initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
     initDocsSweep(opts);
 }
 let emit;
@@ -89,6 +91,25 @@ export function registerDocsCommand(program, emitParam, context) {
             emit.error({ code: "docs_error", message: msg });
         }
     });
+    docs
+        .command("links")
+        .description("Check internal Markdown link targets and heading fragments")
+        .option("--repo <name>", "Limit to one submodule or '.' for parent")
+        .option("--no-fragments", "Check target existence only; skip heading-fragment validation")
+        .option("--strict", "Report findings in archive/audit/changelog docs as errors, not warnings")
+        .option("--check-escapes", "Also flag links that resolve outside their own repo root")
+        .option("--fail", "Exit non-zero when errors are found (advisory by default)")
+        .option("--format <type>", "Output format: human, json", "human")
+        .action(async (opts) => {
+        try {
+            ensureContext(context);
+            await handleLinks(opts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "docs_error", message: msg });
+        }
+    });
     docs
         .command("sweep")
         .description("Surface stalled lifecycle states: stalled plans, cold issues, unverified runbooks")
@@ -185,6 +206,25 @@ async function handleLint(opts) {
     if (errors.length > 0)
         emit.setExitCode(1);
 }
+// --- `harn docs links` ---
+/**
+ * Advisory by default: a clean exit code even with findings, because turning
+ * link health into a gate is an enforcement policy decision for the host, not
+ * something this command should assume. `--fail` is the opt-in for CI or a hook.
+ */
+async function handleLinks(opts) {
+    if (opts.format === "json")
+        emit.config({ format: "json" });
+    const report = await runLinks({
+        repo: opts.repo,
+        noFragments: opts.fragments === false,
+        strict: opts.strict,
+        checkEscapes: opts.checkEscapes,
+    });
+    emit.data({ ...report, advisory: !opts.fail });
+    if (opts.fail && report.error_count > 0)
+        emit.setExitCode(1);
+}
 // --- `harn docs sweep` ---
 async function handleSweep(opts) {
     if (opts.format === "json")

package/dist/commands/doctor.d.ts

@@ -12,14 +12,16 @@
  */
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
+import { type CodexHookAuthorizationResult } from "../core/hooks/codex-authorization.js";
 type Severity = "ok" | "warn" | "fail";
-interface Check {
+export interface Check {
     name: string;
     severity: Severity;
     detail: string;
     hint?: string;
 }
 export declare function registerDoctorCommand(program: Command, emit: EmitContext): void;
-export declare function runChecks(): Check[];
+export declare function runChecks(): Promise<Check[]>;
+export declare function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check;
 export {};
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAanD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAcnC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,EACL,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAe9C,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAyBlD;AA4CD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAoBnF"}

package/dist/commands/doctor.js

@@ -16,9 +16,13 @@ import os from "node:os";
 import path from "node:path";
 import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.js";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.js";
-import { loadAdapterWiring } from "../core/hooks/adapter/wiring.js";
+import { ADAPTER_SPECS } from "../core/hooks/adapter/events.js";
+import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.js";
+import { probeCodexHookAuthorization, } from "../core/hooks/codex-authorization.js";
+import { inspectCodexWslBridge, } from "../core/hooks/codex-wsl-bridge.js";
 import { ADAPTER_BINARIES, ADAPTER_INSTALL_HINTS, ADAPTER_LOGIN_HINTS, } from "../core/workflow/adapters.js";
 import { probeBilling } from "../core/workflow/billing.js";
+import { checkGitHooks, gitHooksInstalled } from "../lib/instructions/git-hooks.js";
 import { findRg, installRg, managedRgPath, rgInstallSupported } from "../lib/tools/ripgrep.js";
 export function registerDoctorCommand(program, emit) {
     program
@@ -36,7 +40,7 @@ export function registerDoctorCommand(program, emit) {
                 emit.text(`ripgrep install failed: ${err.message}\n`);
             }
         }
-        const checks = runChecks();
+        const checks = await runChecks();
         const requiredFailed = checks.some((c) => c.severity === "fail");
         if (opts.json) {
             emit.data({
@@ -64,21 +68,109 @@ export function registerDoctorCommand(program, emit) {
         emit.setExitCode(requiredFailed ? 1 : 0);
     });
 }
-export function runChecks() {
+export async function runChecks() {
+    const codexWslStatus = inspectCodexWslBridge();
+    const codexWslBridge = checkCodexWslBridge(codexWslStatus);
+    // Probe the adapter CLIs before the hook check runs, not in output order:
+    // an unwired adapter only matters if its CLI is actually installed, and
+    // probing once here keeps that join to one spawn per CLI.
+    const workflow = BUILTIN_ADAPTER_IDS.map((id) => ({ id, ...checkWorkflowAdapter(id) }));
+    const installed = workflow.filter((w) => w.installed).map((w) => w.id);
+    const codexAuthorization = await checkCodexHookAuthorization(installed, codexWslStatus);
     return [
         checkNode(),
         checkGit(),
         checkBun(),
         checkRipgrep(),
         checkHarneryDir(),
-        checkAdapterHooks(),
-        ...BUILTIN_ADAPTER_IDS.map(checkWorkflowAdapter),
+        checkAdapterHooks(installed),
+        ...(codexAuthorization ? [codexAuthorization] : []),
+        checkGitHookRegions(),
+        ...(codexWslBridge ? [codexWslBridge] : []),
+        ...workflow.map((w) => w.check),
         checkRestic(),
         checkRclone(),
         checkPlaywright(),
         checkPython(),
     ];
 }
+function checkGitHookRegions() {
+    const root = findCoordProjectRoot();
+    if (!root) {
+        return { name: "git hooks", severity: "ok", detail: "n/a (no .harnery/ above cwd)" };
+    }
+    try {
+        if (!gitHooksInstalled(root)) {
+            const bin = resolveBinName(root);
+            return {
+                name: "git hooks",
+                severity: "warn",
+                detail: `not installed - commits are not guarded against peer-claim conflicts and ` +
+                    `claims never auto-release on commit/checkout; run \`${bin} init\` to install`,
+            };
+        }
+        const { status, issues } = checkGitHooks(root);
+        if (status === "fresh") {
+            return { name: "git hooks", severity: "ok", detail: "managed regions current" };
+        }
+        return { name: "git hooks", severity: "warn", detail: issues.join("; ") };
+    }
+    catch (err) {
+        return {
+            name: "git hooks",
+            severity: "warn",
+            detail: `check failed: ${err.message}`,
+        };
+    }
+}
+function checkCodexWslBridge(status) {
+    if (!status)
+        return null;
+    return {
+        name: "codex:WSL bridge",
+        severity: status.ok ? "ok" : "warn",
+        detail: status.detail,
+        hint: status.ok
+            ? undefined
+            : "forward CODEX_THREAD_ID through WSLENV in the Codex shell environment policy, then start a fresh task",
+    };
+}
+export function codexAuthorizationCheck(result) {
+    const reviewHint = "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";
+    if (result.status === "runnable") {
+        return { name: "codex:hook authorization", severity: "ok", detail: result.detail };
+    }
+    if (result.status === "review_required" || result.status === "disabled") {
+        return {
+            name: "codex:hook authorization",
+            severity: "warn",
+            detail: result.detail,
+            hint: reviewHint,
+        };
+    }
+    return {
+        name: "codex:hook authorization",
+        severity: "warn",
+        detail: `authorization unverified: ${result.detail}`,
+        hint: reviewHint,
+    };
+}
+async function checkCodexHookAuthorization(installedAdapters, codexWslStatus) {
+    const root = findCoordProjectRoot();
+    if (!root || !summarizeAdapterWiring(root).wired.includes("codex"))
+        return null;
+    if (codexWslStatus) {
+        return {
+            name: "codex:hook authorization",
+            severity: "warn",
+            detail: "unverified from WSL; the Windows-native Codex runtime owns this workspace's trust state",
+            hint: "run the host's Windows bridge doctor, or open Codex Desktop Settings > Hooks; start a fresh task after approval",
+        };
+    }
+    if (!installedAdapters.includes("codex"))
+        return null;
+    return codexAuthorizationCheck(await probeCodexHookAuthorization({ cwd: root }));
+}
 function checkRipgrep() {
     const found = findRg();
     if (found) {
@@ -123,6 +215,9 @@ function whichVersion(bin, args = ["--version"]) {
  * One workflow spawn target: is the adapter CLI installed, and how will its
  * headless children bill (subscription login vs API key — see billing.ts)?
  * Missing is a warn, not a fail: workflows degrade to the adapters you have.
+ *
+ * Reports `installed` alongside the check so `checkAdapterHooks` can reuse the
+ * probe instead of spawning every adapter CLI a second time.
  */
 function checkWorkflowAdapter(adapter) {
     const bin = ADAPTER_BINARIES[adapter];
@@ -130,19 +225,25 @@ function checkWorkflowAdapter(adapter) {
     const r = whichVersion(bin);
     if (!r.ok) {
         return {
-            name,
-            severity: "warn",
-            detail: `${bin} missing (workflow --adapter ${adapter} unavailable)`,
-            hint: `${ADAPTER_INSTALL_HINTS[adapter]}  then: ${ADAPTER_LOGIN_HINTS[adapter]}`,
+            check: {
+                name,
+                severity: "warn",
+                detail: `${bin} missing (workflow --adapter ${adapter} unavailable)`,
+                hint: `${ADAPTER_INSTALL_HINTS[adapter]}  then: ${ADAPTER_LOGIN_HINTS[adapter]}`,
+            },
+            installed: false,
         };
     }
     const probe = probeBilling(adapter);
     if (probe.login === "absent" && !probe.apiKeyPresent) {
         return {
-            name,
-            severity: "warn",
-            detail: `${r.out} — installed, but no stored login or API key detected`,
-            hint: ADAPTER_LOGIN_HINTS[adapter],
+            check: {
+                name,
+                severity: "warn",
+                detail: `${r.out} — installed, but no stored login or API key detected`,
+                hint: ADAPTER_LOGIN_HINTS[adapter],
+            },
+            installed: true,
         };
     }
     const billing = probe.mode === "subscription"
@@ -150,7 +251,7 @@ function checkWorkflowAdapter(adapter) {
             ? "billing: subscription"
             : "billing: subscription (login unverifiable, CLI is the authority)"
         : `billing: ${probe.mode} (${probe.apiKeySource})`;
-    return { name, severity: "ok", detail: `${r.out} — ${billing}` };
+    return { check: { name, severity: "ok", detail: `${r.out} — ${billing}` }, installed: true };
 }
 function checkNode() {
     const v = process.versions.node;
@@ -289,13 +390,21 @@ function checkHarneryDir() {
  * loadAdapterWiring — so a bare settings file never false-warns. The remedy is
  * always the same: re-run `<bin> init` (idempotent, additive).
  */
-function checkAdapterHooks() {
+function checkAdapterHooks(installedAdapters = []) {
     const root = findCoordProjectRoot();
     if (!root) {
         return { name: "adapter hooks", severity: "ok", detail: "n/a (no .harnery/ above cwd)" };
     }
     const drift = loadAdapterWiring(root);
-    if (drift.length === 0) {
+    // A adapter with zero harnery hooks is only worth flagging when the project
+    // plainly uses harnery hooks (something else is wired) AND that adapter's CLI
+    // is installed. Both conditions matter: the first keeps a project that has
+    // never run init quiet, the second keeps a project that simply doesn't have
+    // Codex quiet. What's left is the case that reads as healthy but isn't — an
+    // agent can start a session through that adapter and register nothing.
+    const summary = summarizeAdapterWiring(root);
+    const unwired = summary.wired.length > 0 ? summary.unwired.filter((id) => installedAdapters.includes(id)) : [];
+    if (drift.length === 0 && unwired.length === 0) {
         return { name: "adapter hooks", severity: "ok", detail: "wired + current" };
     }
     const bin = resolveBinName(root);
@@ -316,10 +425,23 @@ function checkAdapterHooks() {
         }
         return `${d.settingsFile}: ${bits.join("; ")}`;
     });
+    for (const id of unwired) {
+        parts.push(`${ADAPTER_SPECS[id].settingsFile}: ${id} CLI installed, no harnery hooks wired`);
+    }
     const needsManualRepair = drift.some((d) => d.parseError || d.invalidTopLevelKeys.length > 0 || d.invalidEventKeys.length > 0);
-    const hint = needsManualRepair
-        ? `repair the invalid adapter settings, then run \`${bin} init\` to migrate harnery hooks`
-        : `run \`${bin} init\` to migrate the hook set (idempotent)`;
+    const wireHints = unwired.map((id) => `\`${bin} init --adapter ${id}\``);
+    let hint;
+    if (needsManualRepair) {
+        hint = `repair the invalid adapter settings, then run \`${bin} init\` to migrate harnery hooks`;
+    }
+    else if (drift.length > 0) {
+        hint = `run \`${bin} init\` to migrate the hook set (idempotent)`;
+        if (wireHints.length > 0)
+            hint += `; ${wireHints.join(" and ")} to wire the rest`;
+    }
+    else {
+        hint = `run ${wireHints.join(" and ")} (idempotent, additive)`;
+    }
     return { name: "adapter hooks", severity: "warn", detail: parts.join("  |  "), hint };
 }
 function macOrLinux(mac, linux) {

package/dist/commands/init.d.ts

@@ -18,9 +18,9 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
 import { type AdapterId, type AdapterSpec } from "../core/hooks/adapter/events.js";
-import { type HookGroup, type SettingsFile } from "../core/hooks/adapter/wiring.js";
-export type { HookGroup, SettingsFile };
+import { type SettingsFile } from "../core/hooks/adapter/wiring.js";
 export declare function registerInitCommand(program: Command, emit: EmitContext, binName?: string): void;
+export declare function codexHookReviewAction(adapter: AdapterId): string | null;
 /**
  * Merge agent-hook entries into a adapter settings object in place, idempotently.
  * Preserves every existing hook; rewrites events already wired to

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AAUzC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAYxC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA4I/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,SAAS,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqCvE;AAyDD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmDhG;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkCxF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AAmBzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAyJ/F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,SAAS,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqCvE;AAyDD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmDhG;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkCxF"}

package/dist/commands/init.js

@@ -23,6 +23,7 @@ import { DEFAULT_BIN_NAME, pinnedBinName, stripJsonComments } from "../core/conf
 import { ADAPTER_SPECS } from "../core/hooks/adapter/events.js";
 import { commandWiresSubcommand, groupCommands, makeEntry, } from "../core/hooks/adapter/wiring.js";
 import { applyInstructions, checkInstructions, } from "../lib/instructions/apply.js";
+import { applyGitHooks, checkGitHooks } from "../lib/instructions/git-hooks.js";
 import { HostAddendumError } from "../lib/instructions/host-addendum.js";
 // This file is src/commands/init.ts → harnery package root is two levels up.
 const HARNERY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -55,14 +56,18 @@ export function registerInitCommand(program, emit, binName) {
         // ── --check: read-only drift report on the block + skills ──────────────
         if (opts.check === true) {
             const { status, issues } = checkInstructions(projectRoot, { binName: bin, adapter });
-            const head = status === "fresh"
-                ? "harn init --check: instructions + skills are current"
-                : status === "drift"
+            const gitHooks = checkGitHooks(projectRoot);
+            if (gitHooks.status !== "fresh")
+                issues.push(...gitHooks.issues);
+            const merged = status === "error" ? "error" : gitHooks.status !== "fresh" ? "drift" : status;
+            const head = merged === "fresh"
+                ? "harn init --check: instructions + skills + git hooks are current"
+                : merged === "drift"
                     ? "harn init --check: drift found (re-run `init` to refresh)"
                     : "harn init --check: error";
             const lines = issues.length ? `\n${issues.map((i) => `  ✗ ${i}`).join("\n")}` : "";
             emit.text(`${head}${lines}`);
-            emit.setExitCode(status === "fresh" ? 0 : status === "drift" ? 2 : 1);
+            emit.setExitCode(merged === "fresh" ? 0 : merged === "drift" ? 2 : 1);
             return;
         }
         const dryRun = opts.dryRun === true;
@@ -136,6 +141,9 @@ export function registerInitCommand(program, emit, binName) {
             actions.push(`+ wired ${wired} hook(s), upgraded ${upgraded} stale command(s), and removed ` +
                 `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`);
         }
+        const authorizationReview = codexHookReviewAction(adapter);
+        if (authorizationReview)
+            actions.push(authorizationReview);
         // ── 3. agent-facing instructions block + skills ────────────────────────
         // A misconfigured host addendum aborts here rather than half-writing: the
         // apply step validates the configured source before it touches a file, so
@@ -152,9 +160,22 @@ export function registerInitCommand(program, emit, binName) {
             return;
         }
         actions.push(...applied.actions);
-        emit.text(render(projectRoot, dryRun, actions, applied.warnings));
+        // ── 4. git-hook managed regions ────────────────────────────────────────
+        // Same lifecycle contract as the instructions block: the coordination
+        // content of the consumer's git hooks is machine-owned and versioned;
+        // everything else in those files belongs to the host.
+        const gitHooks = applyGitHooks(projectRoot, { dryRun });
+        actions.push(...gitHooks.actions);
+        emit.text(render(projectRoot, dryRun, actions, [...applied.warnings, ...gitHooks.warnings]));
     });
 }
+export function codexHookReviewAction(adapter) {
+    if (adapter !== "codex")
+        return null;
+    return ("! Codex authorizes hook commands separately. Before starting work, review them in " +
+        "the terminal UI with `/hooks` or in Codex Desktop under Settings > Hooks. " +
+        "After approval, start a fresh task so SessionStart can run.");
+}
 /**
  * Merge agent-hook entries into a adapter settings object in place, idempotently.
  * Preserves every existing hook; rewrites events already wired to

package/dist/commands/instructions.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerInstructionsCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/commands/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/commands/instructions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAcnD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmDrF"}

package/dist/commands/instructions.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { countTokens } from "gpt-tokenizer/model/gpt-4o";
+import { monorepoRoot } from "../core/agents/index.js";
+import { buildInstructionBundle, } from "../lib/instructions/bundle.js";
+export function registerInstructionsCommand(program, emit) {
+    const command = program
+        .command("instructions")
+        .description("Inspect and version the repo-authored instruction bundle loaded by each adapter.");
+    command
+        .command("manifest [paths...]")
+        .description("Emit a machine-readable bundle manifest for one or more working paths")
+        .option("--adapter <adapter>", "claude-code, cursor, codex, or all", "all")
+        .option("--format <type>", "Output format: json or table", "json")
+        .option("-o, --output <file>", "Write the complete JSON manifest to a file")
+        .action((paths, options) => {
+        if (options.format === "json")
+            emit.config({ format: "json" });
+        const coordRoot = monorepoRoot() ?? process.cwd();
+        const adapters = parseAdapters(options.adapter);
+        const profiles = (paths.length > 0 ? paths : [process.cwd()]).flatMap((path) => adapters.map((adapter) => enrichBundle(buildInstructionBundle({ coordRoot, cwd: resolve(path), adapter }), coordRoot)));
+        const manifest = {
+            ok: true,
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            source_commit: gitHead(coordRoot),
+            tokenizer: "o200k_base",
+            coord_root: ".",
+            profile_count: profiles.length,
+            profiles,
+        };
+        if (options.output) {
+            const output = resolve(options.output);
+            writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            emit.data({
+                ok: true,
+                output,
+                schema_version: manifest.schema_version,
+                generated_at: manifest.generated_at,
+                source_commit: manifest.source_commit,
+                profile_count: manifest.profile_count,
+            });
+        }
+        else {
+            emit.data(manifest);
+        }
+    });
+}
+function parseAdapters(value) {
+    if (value === "all")
+        return ["claude-code", "cursor", "codex"];
+    if (value === "claude-code" || value === "cursor" || value === "codex")
+        return [value];
+    throw new Error(`unsupported adapter '${value}' (expected claude-code, cursor, codex, or all)`);
+}
+function enrichBundle(bundle, coordRoot) {
+    const components = bundle.components.map((component) => enrichComponent(component, coordRoot));
+    const canonicalSources = bundle.canonical_sources.map((component) => enrichComponent(component, coordRoot));
+    return {
+        ...bundle,
+        coord_root: ".",
+        components,
+        canonical_sources: canonicalSources,
+        totals: totals(components),
+        canonical_source_totals: totals(canonicalSources),
+    };
+}
+function enrichComponent(component, coordRoot) {
+    const bytes = readFileSync(resolve(coordRoot, component.path));
+    const text = bytes.includes(0) ? null : bytes.toString("utf8");
+    return {
+        ...component,
+        chars: text?.length ?? null,
+        tokens: text === null ? null : countTokens(text),
+    };
+}
+function totals(components) {
+    const roles = ["always_loaded", "just_in_time", "runtime_config"];
+    return {
+        files: components.length,
+        bytes: components.reduce((sum, component) => sum + component.bytes, 0),
+        tokens: components.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+        by_role: Object.fromEntries(roles.map((role) => {
+            const selected = components.filter((component) => component.role === role);
+            return [
+                role,
+                {
+                    files: selected.length,
+                    bytes: selected.reduce((sum, component) => sum + component.bytes, 0),
+                    tokens: selected.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+                },
+            ];
+        })),
+    };
+}
+function gitHead(root) {
+    const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : null;
+}

package/dist/commands/presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/commands/presence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA0BnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwKjF"}
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/commands/presence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA0BnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA8KjF"}

package/dist/commands/presence.js

@@ -133,7 +133,10 @@ export function registerPresenceCommand(program, emit) {
             for (const a of m.agents) {
                 const task = a.task ? `  "${a.task.slice(0, 70)}"` : "";
                 const files = a.files_touched?.length ? `  [${a.files_touched.length} files]` : "";
-                emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}\n`);
+                const lifecycle = a.task_state === "blocked" && a.task_state_reason
+                    ? `${a.task_state}: ${a.task_state_reason}`
+                    : a.task_state;
+                emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}  activity=${a.activity} lifecycle=${lifecycle}\n`);
             }
         }
     });

package/dist/commands/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa1E,OAAO,EAYL,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AA+rBhC;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE7F;AAgND,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CA4EN"}
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa1E,OAAO,EAYL,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AA8rBhC;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE7F;AA+MD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CA2EN"}

package/dist/commands/tunnel.js

@@ -763,7 +763,7 @@ function status(opts) {
         return;
     }
     if (states.length === 1) {
-        // Single tunnel: show the full detail block (backward-compatible).
+        // A single tunnel is clearer as a detail block than as a one-row table.
         statusDetail(states[0]);
         return;
     }
@@ -794,7 +794,7 @@ function logs(opts) {
     const name = resolveName(opts.name);
     const state = readState(name);
     const provider = state?.provider ?? "cloudflare";
-    const which = opts.cloudflared || opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
+    const which = opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
     const path = cachePath("tunnel", which);
     if (!existsSync(path)) {
         emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
@@ -898,7 +898,6 @@ export function registerTunnelCommand(program, emitParam, contextParam) {
         .option("-f, --follow", "follow the log")
         .option("--gate", "tail the gate log (default)")
         .option("--provider", "tail the provider log instead")
-        .option("--cloudflared", "tail the Cloudflare provider log instead (legacy alias)")
         .action(logs);
     const allow = cmd
         .command("allow")

package/dist/core/agents/canonical-emit.d.ts

@@ -28,10 +28,9 @@ export interface CanonicalEmitInput {
  * `agents status`, and no sequence of CLI commands can satisfy it.
  */
 export declare function resolveEmitRoot(start?: string): string | null;
-export declare function emitCanonical(input: CanonicalEmitInput): void;
+export declare function emitCanonical(input: CanonicalEmitInput): boolean;
 /**
- * Normalize the heartbeat's `platform` field (which uses snake_case
- * `claude_code`) to the canonical kebab-case Adapter type.
+ * Normalize the heartbeat's `platform` field to the canonical Adapter type.
  */
 export declare function normalizeAdapter(platform: string | undefined): "claude-code" | "cursor" | "codex";
 //# sourceMappingURL=canonical-emit.d.ts.map

package/dist/core/agents/canonical-emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canonical-emit.d.ts","sourceRoot":"","sources":["../../../src/core/agents/canonical-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAE5E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAsC7D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAIjG"}
+{"version":3,"file":"canonical-emit.d.ts","sourceRoot":"","sources":["../../../src/core/agents/canonical-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAE5E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAwChE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAIjG"}

package/dist/core/agents/canonical-emit.js

@@ -26,10 +26,10 @@ export function resolveEmitRoot(start = process.cwd()) {
 export function emitCanonical(input) {
     const root = resolveEmitRoot();
     if (!root)
-        return;
+        return false;
     const binary = coordBinPath("agent-coord", root);
     if (!binary)
-        return;
+        return false;
     try {
         const args = [
             "emit-event",
@@ -62,15 +62,16 @@ export function emitCanonical(input) {
         if (result.error || result.status !== 0) {
             const why = result.error ? result.error.message : `exit ${result.status}`;
             process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+            return false;
         }
+        return true;
     }
     catch {
-        /* never break the caller */
+        return false;
     }
 }
 /**
- * Normalize the heartbeat's `platform` field (which uses snake_case
- * `claude_code`) to the canonical kebab-case Adapter type.
+ * Normalize the heartbeat's `platform` field to the canonical Adapter type.
  */
 export function normalizeAdapter(platform) {
     if (platform === "cursor")