harnery 0.32.0 → 0.34.0

package/dist/commands/governor.js

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, resolve } from "node:path";
 import { adapterProofInputs, createBuiltinAdapterRegistry, probeBinaryVersion, readAttestation, } from "../core/adapters/index.js";
 import { workflowSubscriptionOnly } from "../core/config.js";
 import { inspectAdapterSpread } from "../core/governor/adapter-spread.js";
-import { approveGovernorPlan, configureGovernorService, createGovernor, governorServiceLogPath, listGovernors, readGovernor, readGovernorPlan, readGovernorServiceConfig, readGovernorServiceStatus, rejectGovernorPlan, requestGovernorServiceStop, retryGovernorPlan, runGovernor, runGovernorServiceDaemon, spawnGovernorService, } from "../core/governor/index.js";
+import { approveGovernorPlan, configureGovernorService, createGovernor, governorServiceLogPath, listGovernorsWithWarnings, readGovernor, readGovernorPlan, readGovernorServiceConfig, readGovernorServiceStatus, rejectGovernorPlan, requestGovernorServiceStop, retryGovernorPlan, runGovernor, runGovernorServiceDaemon, spawnGovernorService, } from "../core/governor/index.js";
 import { findCoordRoot } from "../core/hooks/resolve/coord-root.js";
 import { loadPolicyFile } from "../core/policy/index.js";
 export function registerGovernorCommand(program, emit) {
@@ -83,16 +83,22 @@ export function registerGovernorCommand(program, emit) {
         .option("--json", "Emit complete governor records as JSON")
         .action((opts) => {
         withGovernorRoot(emit, (coordRoot) => {
-            const records = listGovernors(coordRoot);
+            const { records, warnings } = listGovernorsWithWarnings(coordRoot);
             if (opts.json) {
                 emit.config({ format: "json" });
                 emit.data(records);
+                for (const warning of warnings) {
+                    emit.log(renderGovernorListWarning(warning.goal_id, warning.reason), "warn");
+                }
             }
-            else if (records.length === 0) {
+            else if (records.length === 0 && warnings.length === 0) {
                 emit.text("no durable governors\n");
             }
             else {
-                emit.text(`${records.map(renderGovernorRow).join("\n")}\n`);
+                emit.text(`${[
+                    ...records.map(renderGovernorRow),
+                    ...warnings.map((warning) => renderGovernorListWarning(warning.goal_id, warning.reason)),
+                ].join("\n")}\n`);
             }
         });
     });
@@ -693,6 +699,9 @@ function renderPlanRow(plan) {
     const review = plan.review ? `  review:${plan.review.status}` : "";
     return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}${review}`;
 }
+function renderGovernorListWarning(goalId, reason) {
+    return `warning  ${goalId}  unreadable: ${reason}`;
+}
 function delay(ms) {
     return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 }

package/dist/commands/init.d.ts

@@ -17,9 +17,18 @@
  */
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
+import type { EventV3ControlState } from "../core/events/v3/control.js";
 import { type AdapterId, type AdapterSpec } from "../core/hooks/adapter/events.js";
 import { type SettingsFile } from "../core/hooks/adapter/wiring.js";
 export declare function registerInitCommand(program: Command, emit: EmitContext, binName?: string): void;
+/**
+ * Runtime gates bound into an immutable V3 epoch. `init` is the explicit
+ * upgrade boundary: when code or capability profiles change, it archives the
+ * old epoch intact and activates a compatible one instead of letting upgraded
+ * hooks fail closed against stale approvals.
+ */
+export declare function eventLedgerV3RuntimeIssues(control: EventV3ControlState, harneryBuild: string): string[];
+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
@@ -29,8 +38,7 @@ export declare function registerInitCommand(program: Command, emit: EmitContext,
  * `{ command }`) and ensures the root `version` key when the adapter requires
  * one. Pure (no fs/git) so it's unit-testable.
  *
- * The trailing space in the match (`agent-hook ${subcommand} `) is load-bearing:
- * it keeps `stop` from matching `stop-failure`.
+ * Token-aware matching keeps `stop` from matching `stop-failure`.
  */
 export declare function wireHooks(settings: SettingsFile, spec: AdapterSpec, agentHookPath: string, adapter: AdapterId): {
     wired: number;

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,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,CAuJ/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;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAQxE,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AAmBzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA+P/F;AAiBD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,YAAY,EAAE,MAAM,GACnB,MAAM,EAAE,CAoBV;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;;;;;;;;;GAUG;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,CA8CvE;AAwFD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAa1F;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

@@ -16,12 +16,18 @@
  * already wired, so it's safe to re-run. `--dry-run` previews without writing.
  */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_BIN_NAME, pinnedBinName, stripJsonComments } from "../core/config.js";
+import { canonicalJsonV3 } from "../core/events/v3/canonical.js";
+import { ADAPTER_CAPABILITY_PROFILES_V3 } from "../core/events/v3/capabilities.js";
+import { EVENT_V3_SCHEMA_DIGEST } from "../core/events/v3/generated.js";
+import { initializeEventLedgerV3, readEventV3ControlState, sha256V3, } from "../core/events/v3/index.js";
+import { liveEventV3BuildId } from "../core/events/v3/live-routing.js";
 import { ADAPTER_SPECS } from "../core/hooks/adapter/events.js";
-import { commandWiresSubcommand, groupCommands, makeEntry, } from "../core/hooks/adapter/wiring.js";
+import { agentHookPathForProject, commandWiresSubcommand, diffWiring, groupCommands, hookCommand, isAgentHookCommand, 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";
@@ -53,15 +59,76 @@ export function registerInitCommand(program, emit, binName) {
         // init inside any checkout). Without this, re-running init from a host
         // CLI re-stamps the host's name into committed agent-facing surfaces.
         const bin = pinnedBinName(projectRoot) ?? (binName?.trim() ? binName : DEFAULT_BIN_NAME);
-        // ── --check: read-only drift report on the block + skills ──────────────
+        // ── --check: read-only drift report on every init-managed surface ─────
         if (opts.check === true) {
             const { status, issues } = checkInstructions(projectRoot, { binName: bin, adapter });
+            let hookCheckError = false;
+            let hookDrift = false;
+            const settingsPath = resolve(projectRoot, spec.settingsFile);
+            const agentHook = agentHookPathForProject(projectRoot, HARNERY_ROOT);
+            if (!existsSync(settingsPath)) {
+                hookDrift = true;
+                issues.push(`${spec.settingsFile}: missing (re-run init)`);
+            }
+            else {
+                try {
+                    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+                    const hookDiff = diffWiring(settings, spec, { agentHookPath: agentHook, adapter });
+                    hookDrift =
+                        hookDiff.missing.length > 0 ||
+                            hookDiff.stale.length > 0 ||
+                            hookDiff.duplicates.length > 0 ||
+                            hookDiff.misplaced.length > 0 ||
+                            hookDiff.orphans.length > 0 ||
+                            hookDiff.invalidTopLevelKeys.length > 0 ||
+                            hookDiff.invalidEventKeys.length > 0;
+                    if (hookDiff.missing.length > 0) {
+                        issues.push(`${spec.settingsFile}: missing hooks (${hookDiff.missing.map((e) => e.settingsKey).join(", ")})`);
+                    }
+                    if (hookDiff.stale.length > 0) {
+                        issues.push(`${spec.settingsFile}: stale hook commands (${hookDiff.stale.map((e) => e.settingsKey).join(", ")})`);
+                    }
+                    if (hookDiff.duplicates.length > 0) {
+                        issues.push(`${spec.settingsFile}: duplicate hooks (${hookDiff.duplicates.map((e) => e.settingsKey).join(", ")})`);
+                    }
+                    if (hookDiff.misplaced.length > 0) {
+                        issues.push(`${spec.settingsFile}: hooks under the wrong event (${hookDiff.misplaced.map((e) => e.subcommand).join(", ")})`);
+                    }
+                    if (hookDiff.orphans.length > 0) {
+                        issues.push(`${spec.settingsFile}: obsolete hooks (${hookDiff.orphans.join(", ")})`);
+                    }
+                    if (hookDiff.invalidTopLevelKeys.length > 0) {
+                        issues.push(`${spec.settingsFile}: invalid fields (${hookDiff.invalidTopLevelKeys.join(", ")})`);
+                    }
+                    if (hookDiff.invalidEventKeys.length > 0) {
+                        issues.push(`${spec.settingsFile}: unsupported events (${hookDiff.invalidEventKeys.join(", ")})`);
+                    }
+                }
+                catch (error) {
+                    hookCheckError = true;
+                    issues.push(`${spec.settingsFile}: invalid JSON (${error.message})`);
+                }
+            }
             const gitHooks = checkGitHooks(projectRoot);
             if (gitHooks.status !== "fresh")
                 issues.push(...gitHooks.issues);
-            const merged = status === "error" ? "error" : gitHooks.status !== "fresh" ? "drift" : status;
+            const ledger = readEventV3ControlState(projectRoot);
+            if (ledger.state !== "active")
+                issues.push(`event ledger V3 is ${ledger.state}`);
+            const ledgerRuntimeIssues = eventLedgerV3RuntimeIssues(ledger, gitBuild(HARNERY_ROOT));
+            if (ledgerRuntimeIssues.length > 0) {
+                issues.push(`event ledger V3 is runtime-stale (${ledgerRuntimeIssues.join(", ")})`);
+            }
+            const merged = status === "error" || hookCheckError
+                ? "error"
+                : hookDrift ||
+                    gitHooks.status !== "fresh" ||
+                    ledger.state !== "active" ||
+                    ledgerRuntimeIssues.length > 0
+                    ? "drift"
+                    : status;
             const head = merged === "fresh"
-                ? "harn init --check: instructions + skills + git hooks are current"
+                ? "harn init --check: hooks + instructions + skills + event ledger V3 are current"
                 : merged === "drift"
                     ? "harn init --check: drift found (re-run `init` to refresh)"
                     : "harn init --check: error";
@@ -109,9 +176,37 @@ export function registerInitCommand(program, emit, binName) {
             if (stamp)
                 actions.push(stamp);
         }
+        // ── 1d. universal V3 event ledger ────────────────────────────────────
+        if (dryRun) {
+            const ledger = readEventV3ControlState(projectRoot);
+            const runtimeIssues = eventLedgerV3RuntimeIssues(ledger, gitBuild(HARNERY_ROOT));
+            actions.push(ledger.state === "active" && runtimeIssues.length === 0
+                ? "· event ledger V3 is active"
+                : ledger.state === "active"
+                    ? `+ would refresh event ledger V3 runtime profile (${runtimeIssues.join(", ")})`
+                    : `+ would initialize event ledger V3 (current state: ${ledger.state})`);
+        }
+        else {
+            const harneryBuild = gitBuild(HARNERY_ROOT);
+            const ledgerBefore = readEventV3ControlState(projectRoot);
+            const runtimeIssues = eventLedgerV3RuntimeIssues(ledgerBefore, harneryBuild);
+            const initialized = initializeEventLedgerV3({
+                coordRoot: projectRoot,
+                harneryBuild,
+                hostBuild: gitBuild(projectRoot),
+                configDigest: digestConfig(resolve(coordDir, "config.jsonc")),
+                approvalRecordId: "harnery-init-v3-universal",
+                forceNewEpoch: runtimeIssues.length > 0,
+            });
+            actions.push(initialized.archived_epoch
+                ? `+ refreshed event ledger V3 runtime profile (${runtimeIssues.join(", ")}); archived the prior epoch intact`
+                : initialized.initialized
+                    ? "+ initialized event ledger V3"
+                    : "· event ledger V3 already active");
+        }
         // ── 2. adapter hooks ───────────────────────────────────────────────────
         const settingsPath = resolve(projectRoot, spec.settingsFile);
-        const agentHook = relative(projectRoot, resolve(HARNERY_ROOT, "bin", "agent-hook"));
+        const agentHook = agentHookPathForProject(projectRoot, HARNERY_ROOT);
         let settings;
         if (existsSync(settingsPath)) {
             try {
@@ -133,14 +228,17 @@ export function registerInitCommand(program, emit, binName) {
         }
         else if (dryRun) {
             actions.push(`+ would wire ${wired} hook(s), upgrade ${upgraded} stale command(s), and remove ` +
-                `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`);
+                `${removed} obsolete/duplicate command(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`);
         }
         else {
             mkdirSync(dirname(settingsPath), { recursive: true });
             writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
             actions.push(`+ wired ${wired} hook(s), upgraded ${upgraded} stale command(s), and removed ` +
-                `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`);
+                `${removed} obsolete/duplicate command(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
@@ -166,6 +264,50 @@ export function registerInitCommand(program, emit, binName) {
         emit.text(render(projectRoot, dryRun, actions, [...applied.warnings, ...gitHooks.warnings]));
     });
 }
+function gitBuild(root) {
+    const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    const commit = result.status === 0 ? result.stdout.trim() : "";
+    return /^[0-9a-f]{40,64}$/.test(commit)
+        ? commit
+        : createHash("sha256").update(resolve(root)).digest("hex");
+}
+function digestConfig(path) {
+    return sha256V3(existsSync(path) ? readFileSync(path) : Buffer.from("{}\n"));
+}
+/**
+ * Runtime gates bound into an immutable V3 epoch. `init` is the explicit
+ * upgrade boundary: when code or capability profiles change, it archives the
+ * old epoch intact and activates a compatible one instead of letting upgraded
+ * hooks fail closed against stale approvals.
+ */
+export function eventLedgerV3RuntimeIssues(control, harneryBuild) {
+    if (control.state !== "active")
+        return [];
+    const issues = [];
+    const profile = control.genesis.profile;
+    if (profile.initial_schema_digest !== EVENT_V3_SCHEMA_DIGEST)
+        issues.push("schema digest");
+    if (profile.contract_source_digest !== EVENT_V3_SCHEMA_DIGEST)
+        issues.push("contract digest");
+    if (!profile.producer_build_ids.includes(liveEventV3BuildId(harneryBuild))) {
+        issues.push("producer build");
+    }
+    const expectedCapabilities = Object.values(ADAPTER_CAPABILITY_PROFILES_V3).map((value) => sha256V3(canonicalJsonV3(value)));
+    if (expectedCapabilities.some((digest) => !profile.adapter_capability_profile_digests.includes(digest))) {
+        issues.push("adapter capabilities");
+    }
+    return issues;
+}
+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
@@ -175,8 +317,7 @@ export function registerInitCommand(program, emit, binName) {
  * `{ command }`) and ensures the root `version` key when the adapter requires
  * one. Pure (no fs/git) so it's unit-testable.
  *
- * The trailing space in the match (`agent-hook ${subcommand} `) is load-bearing:
- * it keeps `stop` from matching `stop-failure`.
+ * Token-aware matching keeps `stop` from matching `stop-failure`.
  */
 export function wireHooks(settings, spec, agentHookPath, adapter) {
     if (spec.rootVersion !== undefined && settings.version === undefined) {
@@ -188,30 +329,41 @@ export function wireHooks(settings, spec, agentHookPath, adapter) {
     let already = 0;
     let removed = 0;
     let upgraded = 0;
-    for (const { settingsKey, subcommand } of spec.legacyEvents ?? []) {
-        const groups = settings.hooks[settingsKey] ?? [];
-        const kept = groups.filter((group) => !groupCommands(group).some((command) => commandWiresSubcommand(command, subcommand)));
-        removed += groups.length - kept.length;
-        if (kept.length === 0)
-            delete settings.hooks[settingsKey];
-        else
-            settings.hooks[settingsKey] = kept;
+    for (const { subcommand } of spec.legacyEvents ?? []) {
+        for (const settingsKey of Object.keys(settings.hooks)) {
+            removed += removeCommandsFromKey(settings, settingsKey, (command) => commandWiresSubcommand(command, subcommand));
+        }
     }
     for (const { settingsKey, subcommand } of spec.events) {
         const command = hookCommand(spec, agentHookPath, subcommand, adapter);
-        const groups = settings.hooks[settingsKey] ?? [];
         let present = false;
+        for (const key of Object.keys(settings.hooks)) {
+            if (key === settingsKey)
+                continue;
+            removed += removeCommandsFromKey(settings, key, (candidate) => commandWiresSubcommand(candidate, subcommand));
+        }
+        const groups = settings.hooks[settingsKey] ?? [];
+        const nextGroups = [];
         for (const group of groups) {
-            upgraded += rewriteStaleCommands(group, subcommand, command, () => {
+            const normalized = normalizeEventGroup(group, subcommand, command, present);
+            if (normalized.found && !present)
                 present = true;
-            });
+            upgraded += normalized.upgraded;
+            removed += normalized.removed;
+            if (normalized.group)
+                nextGroups.push(normalized.group);
         }
+        if (nextGroups.length > 0)
+            settings.hooks[settingsKey] = nextGroups;
+        else
+            delete settings.hooks[settingsKey];
         if (present) {
             already++;
             continue;
         }
-        groups.push(makeEntry(spec.entryShape, command));
-        settings.hooks[settingsKey] = groups;
+        const current = settings.hooks[settingsKey] ?? [];
+        current.push(makeEntry(spec.entryShape, command));
+        settings.hooks[settingsKey] = current;
         wired++;
     }
     return { wired, already, removed, upgraded };
@@ -226,40 +378,79 @@ export function wireHooks(settings, spec, agentHookPath, adapter) {
  * that don't set the var. Only the env expansion is quoted so the
  * `agent-hook <subcommand> ` wiring match stays byte-identical.
  */
-function hookCommand(spec, agentHookPath, subcommand, adapter) {
-    const anchor = spec.projectDirEnv ? `"\${${spec.projectDirEnv}:-.}"/` : "";
-    return `bash ${anchor}${agentHookPath} ${subcommand} --adapter ${adapter}`;
-}
-/**
- * Rewrite any harnery-owned command for `subcommand` inside one hook group to
- * the canonical form, in place. Returns the number of commands rewritten and
- * calls `onPresent` when the subcommand is wired in this group at all.
- */
-function rewriteStaleCommands(group, subcommand, canonical, onPresent) {
-    let rewritten = 0;
+function normalizeEventGroup(group, subcommand, canonical, alreadyFound) {
+    let found = false;
+    let upgraded = 0;
+    let removed = 0;
     if ("command" in group && typeof group.command === "string") {
         if (commandWiresSubcommand(group.command, subcommand)) {
-            onPresent();
+            if (alreadyFound)
+                return { group: null, found: true, upgraded: 0, removed: 1 };
+            found = true;
             if (group.command !== canonical) {
                 group.command = canonical;
-                rewritten++;
+                upgraded++;
             }
         }
     }
     if ("hooks" in group && Array.isArray(group.hooks)) {
+        const kept = [];
         for (const hook of group.hooks) {
-            if (typeof hook.command !== "string")
+            if (typeof hook.command !== "string" || !commandWiresSubcommand(hook.command, subcommand)) {
+                kept.push(hook);
                 continue;
-            if (!commandWiresSubcommand(hook.command, subcommand))
+            }
+            if (alreadyFound || found) {
+                removed++;
                 continue;
-            onPresent();
+            }
+            found = true;
             if (hook.command !== canonical) {
                 hook.command = canonical;
-                rewritten++;
+                upgraded++;
             }
+            kept.push(hook);
         }
+        group.hooks = kept;
+        if (group.hooks.length === 0)
+            return { group: null, found, upgraded, removed };
     }
-    return rewritten;
+    return { group, found, upgraded, removed };
+}
+/** Remove matching command handlers while preserving unrelated handlers in a mixed group. */
+function removeCommandsFromKey(settings, settingsKey, predicate) {
+    const groups = settings.hooks?.[settingsKey];
+    if (!Array.isArray(groups))
+        return 0;
+    let removed = 0;
+    const kept = [];
+    for (const group of groups) {
+        if ("command" in group && typeof group.command === "string") {
+            if (predicate(group.command))
+                removed++;
+            else
+                kept.push(group);
+            continue;
+        }
+        if ("hooks" in group && Array.isArray(group.hooks)) {
+            const handlers = group.hooks.filter((hook) => {
+                if (typeof hook.command !== "string" || !predicate(hook.command))
+                    return true;
+                removed++;
+                return false;
+            });
+            group.hooks = handlers;
+            if (handlers.length > 0)
+                kept.push(group);
+            continue;
+        }
+        kept.push(group);
+    }
+    if (kept.length === 0)
+        delete settings.hooks?.[settingsKey];
+    else
+        settings.hooks[settingsKey] = kept;
+    return removed;
 }
 /**
  * Inverse of {@link wireHooks}: strip every harnery-owned hook entry from a
@@ -276,21 +467,12 @@ export function unwireHooks(settings) {
         return { removed: 0, remaining: 0 };
     let removed = 0;
     for (const key of Object.keys(settings.hooks)) {
-        const groups = settings.hooks[key];
-        if (!Array.isArray(groups))
-            continue;
-        const kept = groups.filter((g) => !groupCommands(g).some((c) => c.includes("agent-hook ")));
-        removed += groups.length - kept.length;
-        // removing the emptied hook key is the intent (tiny one-shot object)
-        if (kept.length === 0)
-            delete settings.hooks[key];
-        else
-            settings.hooks[key] = kept;
+        removed += removeCommandsFromKey(settings, key, isAgentHookCommand);
     }
     let remaining = 0;
     for (const groups of Object.values(settings.hooks)) {
         if (Array.isArray(groups))
-            remaining += groups.length;
+            remaining += groups.flatMap(groupCommands).length;
     }
     // drop the now-empty hooks object so callers see a clean shape
     if (Object.keys(settings.hooks).length === 0)

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/journal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/commands/journal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA6BnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA2RrF"}
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/commands/journal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8BnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAgRrF"}

package/dist/commands/journal.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, watch } from "node:fs";
 import { resolve as resolvePath } from "node:path";
-import { emitCanonical, normalizeAdapter, readHeartbeat } from "../core/agents/index.js";
+import { monorepoRoot } from "../core/agents/index.js";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.js";
 import { resolveBinName } from "../core/config.js";
 import { appendEntry, archiveJournal, currentOwnerOrThrow, JOURNAL_CATEGORIES, journalDir, journalPath, lintJournal, listArchives, loadJournal, parseJournal, pruneArchives, resolveOwnerByName, sweepOrphanJournals, } from "../core/journal/index.js";
 /**
@@ -30,17 +31,6 @@ export function registerJournalCommand(program, emitParam) {
         try {
             const owner = currentOwnerOrThrow();
             const doc = appendEntry(owner, cat, body);
-            const hb = readHeartbeat(owner);
-            emitCanonical({
-                type: "state.journal_append",
-                owner,
-                session: hb?.session_id ?? owner,
-                adapter: normalizeAdapter(hb?.platform),
-                data: {
-                    category: cat,
-                    body_summary: body.length > 1000 ? `${body.slice(0, 997)}...` : body,
-                },
-            });
             emit.data({
                 instance_id: owner,
                 name: doc.header.name,
@@ -313,7 +303,8 @@ function runRead(opts) {
         });
         process.exit(1);
     }
-    const hb = readHeartbeat(owner);
+    const root = monorepoRoot();
+    const hb = root ? readLiveCoordinationRow(root, owner) : null;
     const staleBanner = renderStaleBannerIfNeeded(hb?.last_heartbeat);
     process.stdout.write(`${staleBanner + renderJournal(doc, limit)}\n`); // lint-ok-emission: pretty render, multi-line markdown for direct TTY/pipe consumption
 }

package/dist/commands/ledger-v3.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+/** Inspect or initialize the universal V3 event ledger. */
+export declare function registerLedgerV3Command(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=ledger-v3.d.ts.map

package/dist/commands/ledger-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-v3.d.ts","sourceRoot":"","sources":["../../src/commands/ledger-v3.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAQ1E,2DAA2D;AAC3D,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+DN"}