harnery 0.32.0 → 0.34.0

package/dist/core/agents/finalization.js

@@ -9,8 +9,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { agentsFinalizationRoots } from "../config.js";
-import { readStreamTailBounded } from "./events/consume.js";
-const CLAIM_HISTORY_CAP_BYTES = 128 * 1024 * 1024;
+import { readFinalizationScopeV3 } from "../events/v3/finalization-view.js";
+import { liveInstanceIdV3, resolveLiveEventLedgerRouteV3 } from "../events/v3/live-routing.js";
 const GIT_DISCOVERY_VARS = [
     "GIT_DIR",
     "GIT_WORK_TREE",
@@ -26,32 +26,17 @@ const GIT_DISCOVERY_VARS = [
  * a commit. Current heartbeat claims describe dirty ownership; this history is
  * what keeps the touched repository in scope until its commits are pushed.
  */
-export function readSessionWriteClaims(coordRoot, instanceId, sessionId) {
-    const streamPath = join(coordRoot, ".harnery", "events.ndjson");
-    const { text, truncated } = readStreamTailBounded(streamPath, CLAIM_HISTORY_CAP_BYTES);
-    const paths = new Set();
-    let sawSessionStart = false;
-    for (const line of text.split("\n")) {
-        if (line.trim().length === 0)
-            continue;
-        try {
-            const event = JSON.parse(line);
-            if (event.instance_id !== instanceId || event.session_id !== sessionId)
-                continue;
-            if (event.event_type === "session.start")
-                sawSessionStart = true;
-            if (event.event_type === "claim.acquire" &&
-                event.data?.mode === "write" &&
-                typeof event.data.path === "string") {
-                paths.add(event.data.path);
-            }
-        }
-        catch {
-            // Ignore malformed and crash-truncated event lines, matching the
-            // canonical stream consumer's recovery behavior.
-        }
+export function readSessionWriteClaims(coordRoot, instanceId, _sessionId) {
+    const route = resolveLiveEventLedgerRouteV3(coordRoot);
+    if (route.state === "blocked")
+        return { paths: [], complete: false };
+    try {
+        const scope = readFinalizationScopeV3(coordRoot, liveInstanceIdV3(instanceId));
+        return { paths: scope.files_touched, complete: true };
+    }
+    catch {
+        return { paths: [], complete: false };
     }
-    return { paths: [...paths], complete: !truncated || sawSessionStart };
 }
 function git(args, cwd) {
     const env = { ...process.env };
@@ -303,6 +288,50 @@ function repoSyncState(repoRoot) {
         return "unverifiable";
     return containing.stdout.trim().length > 0 ? "synced" : "unpushed";
 }
+function repoIsBehindUpstream(repoRoot) {
+    if (!repoHasRemote(repoRoot))
+        return false;
+    const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], repoRoot);
+    if (upstream.status !== 0)
+        return false;
+    const behind = git(["rev-list", "--count", "HEAD..@{upstream}"], repoRoot);
+    return behind.status === 0 && Number.parseInt(behind.stdout.trim(), 10) > 0;
+}
+function rootSubmoduleFreshness(repoRoot) {
+    const modules = git(["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"], repoRoot);
+    if (modules.status !== 0 || modules.stdout.trim().length === 0) {
+        return { stale: [], diverged: [] };
+    }
+    const stale = [];
+    const diverged = [];
+    for (const line of modules.stdout.trim().split("\n")) {
+        const path = line.trim().split(/\s+/).at(-1);
+        if (!path)
+            continue;
+        const target = git(["rev-parse", `HEAD:${path}`], repoRoot);
+        const checkout = git(["rev-parse", "HEAD"], join(repoRoot, path));
+        if (target.status !== 0 || checkout.status !== 0) {
+            stale.push(path);
+            continue;
+        }
+        const targetSha = target.stdout.trim();
+        const checkoutSha = checkout.stdout.trim();
+        if (targetSha === checkoutSha)
+            continue;
+        const checkoutBehind = git(["merge-base", "--is-ancestor", checkoutSha, targetSha], join(repoRoot, path));
+        if (checkoutBehind.status === 0) {
+            stale.push(path);
+            continue;
+        }
+        const checkoutAhead = git(["merge-base", "--is-ancestor", targetSha, checkoutSha], join(repoRoot, path));
+        // A checkout ahead of its gitlink is in-flight local work. Its owning
+        // session is responsible for the eventual pointer bump; unrelated turns
+        // must not be blocked globally while that work is active.
+        if (checkoutAhead.status !== 0)
+            diverged.push(path);
+    }
+    return { stale: stale.sort(), diverged: diverged.sort() };
+}
 /** Compare gitlink commits without treating dirty contents inside the child as a pointer change. */
 function gitlinkIsDirty(parentRoot, gitlink) {
     const head = git(["rev-parse", `HEAD:${gitlink}`], parentRoot);
@@ -318,6 +347,9 @@ function gitlinkIsDirty(parentRoot, gitlink) {
 /** Check that this session's held paths are committed and their repositories are pushed. */
 export function checkGitFinalization(coordRoot, heldPaths, options = {}) {
     const root = resolve(coordRoot);
+    // Repository discovery resolves symlinks. Use the same physical base for
+    // display labels so macOS /var -> /private/var aliases stay repo-relative.
+    const labelRoot = physicalPath(root) ?? root;
     const repos = new Map();
     const hostOutputPaths = new Set();
     const unsupportedPaths = [];
@@ -346,42 +378,50 @@ export function checkGitFinalization(coordRoot, heldPaths, options = {}) {
         for (const repoPath of work.paths) {
             if (work.gitlinks.has(repoPath)) {
                 if (gitlinkIsDirty(work.root, repoPath)) {
-                    const label = repoLabel(root, work.root);
+                    const label = repoLabel(labelRoot, work.root);
                     dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
                 }
                 continue;
             }
             const status = git(["status", "--porcelain=v1", "--untracked-files=all", "--", repoPath], work.root);
             if (status.status !== 0) {
-                unverifiablePaths.push(join(repoLabel(root, work.root), repoPath).replaceAll("\\", "/"));
+                unverifiablePaths.push(join(repoLabel(labelRoot, work.root), repoPath).replaceAll("\\", "/"));
             }
             else if (status.stdout.length > 0) {
-                const label = repoLabel(root, work.root);
+                const label = repoLabel(labelRoot, work.root);
                 dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
             }
         }
         const syncState = repoSyncState(work.root);
-        const label = repoLabel(root, work.root);
+        const label = repoLabel(labelRoot, work.root);
         if (syncState === "unpushed")
             unpushedRepos.push(label);
         if (syncState === "unverifiable")
             unverifiableRepos.push(label);
     }
+    const behindRepos = repoIsBehindUpstream(root) ? ["."] : [];
+    const submoduleFreshness = rootSubmoduleFreshness(root);
     const result = {
         ok: false,
         claim_history_complete: options.claimHistoryComplete ?? true,
         dirty_paths: [...dirtyPaths].sort(),
         unpushed_repos: [...new Set(unpushedRepos)].sort(),
+        behind_repos: behindRepos,
+        stale_submodules: submoduleFreshness.stale,
+        diverged_submodules: submoduleFreshness.diverged,
         host_output_paths: [...hostOutputPaths].sort(),
         unsupported_paths: unsupportedPaths.sort((a, b) => a.path.localeCompare(b.path) || a.reason.localeCompare(b.reason)),
         unverifiable_paths: [...new Set(unverifiablePaths)].sort(),
         unverifiable_repos: [...new Set(unverifiableRepos)].sort(),
-        repos_checked: [...repos.keys()].map((repo) => repoLabel(root, repo)).sort(),
+        repos_checked: [...repos.keys()].map((repo) => repoLabel(labelRoot, repo)).sort(),
     };
     result.ok =
         result.claim_history_complete &&
             result.dirty_paths.length === 0 &&
             result.unpushed_repos.length === 0 &&
+            result.behind_repos.length === 0 &&
+            result.stale_submodules.length === 0 &&
+            result.diverged_submodules.length === 0 &&
             result.unsupported_paths.length === 0 &&
             result.unverifiable_paths.length === 0 &&
             result.unverifiable_repos.length === 0;
@@ -398,6 +438,15 @@ export function formatGitFinalizationFailure(result, bin) {
     if (result.unpushed_repos.length > 0) {
         lines.push("Repositories with commits not on their remote:", ...result.unpushed_repos.map((repo) => `  - ${repo}`));
     }
+    if (result.behind_repos.length > 0) {
+        lines.push("Repositories behind their upstream:", ...result.behind_repos.map((repo) => `  - ${repo}`));
+    }
+    if (result.stale_submodules.length > 0) {
+        lines.push("Submodule checkouts behind their parent gitlinks:", ...result.stale_submodules.map((path) => `  - ${path}`));
+    }
+    if (result.diverged_submodules.length > 0) {
+        lines.push("Submodule checkouts diverged from their parent gitlinks:", ...result.diverged_submodules.map((path) => `  - ${path}`));
+    }
     if (result.unsupported_paths.length > 0) {
         lines.push("Paths without an authorized end-turn disposition:", ...result.unsupported_paths.map(({ path, reason }) => `  - ${path}: ${unsupportedReasonMessage(reason)}`));
     }
@@ -409,10 +458,18 @@ export function formatGitFinalizationFailure(result, bin) {
     }
     if (result.dirty_paths.length > 0 ||
         result.unpushed_repos.length > 0 ||
+        result.behind_repos.length > 0 ||
+        result.stale_submodules.length > 0 ||
+        result.diverged_submodules.length > 0 ||
         result.unverifiable_paths.length > 0 ||
         result.unverifiable_repos.length > 0) {
         lines.push(`Commit and push the owned Git work, then rerun \`${bin} agents status --end-turn\`.`);
     }
+    if (result.behind_repos.length > 0 ||
+        result.stale_submodules.length > 0 ||
+        result.diverged_submodules.length > 0) {
+        lines.push("Run the host repository's safe sync command, resolve any reported submodule state, then rerun the guarded status.");
+    }
     if (result.unsupported_paths.length > 0) {
         lines.push("For a legacy claim, add the containing Git repository or intentional non-Git output root to the project's `agents.finalizationRoots`, then rerun the guarded status. For new work, start the task from the target Git project or configure that root before editing.");
     }

package/dist/core/agents/index.d.ts

@@ -1,14 +1,14 @@
 /**
  * agent-coord library public exports.
  *
- * `coord-client`: coordination helpers
- * (Heartbeat reader, owner-resolver via ppid-walk, monorepo-root finder).
- * Imported by every TS caller that needs to read coord state.
+ * `coord-client`: V3 producer identity resolution, ppid-map attribution, and
+ * coordination-root discovery.
  *
- * `canonical-emit`: fire-and-forget client for the canonical event stream;
- * spawns `bin/agent-coord emit-event` and never blocks the caller.
+ * `canonical-emit`: canonical V3 observation helpers.
  */
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
+export * from "./live-observation-v3.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/core/agents/index.js

@@ -1,13 +1,13 @@
 /**
  * agent-coord library public exports.
  *
- * `coord-client`: coordination helpers
- * (Heartbeat reader, owner-resolver via ppid-walk, monorepo-root finder).
- * Imported by every TS caller that needs to read coord state.
+ * `coord-client`: V3 producer identity resolution, ppid-map attribution, and
+ * coordination-root discovery.
  *
- * `canonical-emit`: fire-and-forget client for the canonical event stream;
- * spawns `bin/agent-coord emit-event` and never blocks the caller.
+ * `canonical-emit`: canonical V3 observation helpers.
  */
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
+export * from "./live-observation-v3.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";

package/dist/core/agents/live-authority-v3.d.ts

@@ -0,0 +1,59 @@
+import type { Adapter } from "../adapter.js";
+import type { EventV3WriteMode } from "../events/v3/control.js";
+import { type RecordCoordinationAuthorityV3Result } from "../events/v3/producers/coordination-recorder.js";
+export declare const LIVE_COORDINATION_V3_PRODUCER_ID: "prd_agent-coord";
+export declare class LiveCoordinationAuthorityV3Error extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export type LiveCoordinationAuthorityV3Result = {
+    state: "unchanged";
+} | {
+    state: "recorded";
+    result: RecordCoordinationAuthorityV3Result;
+};
+export interface ReopenedLiveCoordinationGenerationV3 {
+    state: "reopened";
+    adapter: Adapter;
+    prior_generation_id: `gen_${string}`;
+    generation_id: `gen_${string}`;
+}
+interface LiveAuthorityBaseV3 {
+    coordRoot: string;
+    owner: string;
+    subject?: string;
+    nativeSessionId: string;
+    adapter: Adapter;
+    observationId?: string;
+}
+/**
+ * Open a fresh derived generation for a human-facing session that is executing
+ * again after an authoritative terminal. The terminal generation is never
+ * changed or reused.
+ */
+export declare function reopenLiveCoordinationGenerationV3(input: {
+    coordRoot: string;
+    owner: string;
+    nativeSessionId: string;
+}): ReopenedLiveCoordinationGenerationV3;
+export declare function recordLiveTaskChangeV3(input: LiveAuthorityBaseV3 & {
+    task: string;
+}): LiveCoordinationAuthorityV3Result;
+export declare function recordLiveLifecycleChangeV3(input: LiveAuthorityBaseV3 & {
+    state: "active" | "blocked" | "done";
+    reason?: string;
+    suggestedSessionName?: string;
+    observedAt?: string;
+}): LiveCoordinationAuthorityV3Result;
+export declare function recordLiveClaimChangeV3(input: LiveAuthorityBaseV3 & {
+    operation: "acquired" | "released";
+    path: string;
+    access?: "read" | "write";
+}): LiveCoordinationAuthorityV3Result;
+export declare function recordLiveIdentityChangeV3(input: LiveAuthorityBaseV3 & {
+    name: string;
+    identityId: string;
+}): LiveCoordinationAuthorityV3Result;
+export declare function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode;
+export {};
+//# sourceMappingURL=live-authority-v3.d.ts.map

package/dist/core/agents/live-authority-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-authority-v3.d.ts","sourceRoot":"","sources":["../../../src/core/agents/live-authority-v3.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAehE,OAAO,EACL,KAAK,mCAAmC,EAEzC,MAAM,iDAAiD,CAAC;AAoBzD,eAAO,MAAM,gCAAgC,EAAG,iBAA0B,CAAC;AAE3E,qBAAa,gCAAiC,SAAQ,KAAK;aAC7B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AAED,MAAM,MAAM,iCAAiC,GACzC;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,mCAAmC,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,oCAAoC;IACnD,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,OAAO,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,OAAO,MAAM,EAAE,CAAC;CAChC;AAED,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,oCAAoC,CAkDvC;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C,iCAAiC,CAiCnC;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,mBAAmB,GAAG;IAC3B,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,iCAAiC,CAmCnC;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,mBAAmB,GAAG;IAC3B,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B,GACA,iCAAiC,CAuCnC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChE,iCAAiC,CAuBnC;AAuDD,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAI/E"}

package/dist/core/agents/live-authority-v3.js

@@ -0,0 +1,233 @@
+import { randomUUID } from "node:crypto";
+import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.js";
+import { readCoordinationViewV3, requireAuthoritySafeCoordinationViewV3, } from "../events/v3/coordination-view.js";
+import { LIVE_HOOK_V3_PRODUCER_ID, liveInstanceIdV3, livePlatformV3, resolveLiveEventLedgerRouteV3, } from "../events/v3/live-routing.js";
+import { recordCoordinationAuthorityV3, } from "../events/v3/producers/coordination-recorder.js";
+import { readTerminalHookProducerStateV3, recordHookSignalV3, } from "../events/v3/producers/recorder.js";
+import { acquireClaim, readHeartbeat, releaseClaim, setIdentityCache, setLifecycleCache, setTask, } from "./state/heartbeat-writer.js";
+import { ensureLiveCoordinationHeartbeat, liveCoordinationAdapterV3, } from "./state/live-coordination-view.js";
+import { recordNameAssumption } from "./state/names.js";
+export const LIVE_COORDINATION_V3_PRODUCER_ID = "prd_agent-coord";
+export class LiveCoordinationAuthorityV3Error extends Error {
+    reason;
+    constructor(reason) {
+        super(`event_v3_coordination_authority:${reason}`);
+        this.reason = reason;
+        this.name = "LiveCoordinationAuthorityV3Error";
+    }
+}
+/**
+ * Open a fresh derived generation for a human-facing session that is executing
+ * again after an authoritative terminal. The terminal generation is never
+ * changed or reused.
+ */
+export function reopenLiveCoordinationGenerationV3(input) {
+    const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
+    if (route.state === "blocked")
+        throw new LiveCoordinationAuthorityV3Error(route.reason);
+    const instanceId = liveInstanceIdV3(input.owner);
+    const terminal = readTerminalHookProducerStateV3(input.coordRoot, input.nativeSessionId, instanceId);
+    if (!terminal) {
+        throw new LiveCoordinationAuthorityV3Error("terminal_generation_identity_missing");
+    }
+    const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(input.coordRoot));
+    const terminalView = view.terminal_generations[terminal.generation_id];
+    if (!terminalView || terminalView.instance_id !== instanceId) {
+        throw new LiveCoordinationAuthorityV3Error("terminal_generation_authority_missing");
+    }
+    if (terminalView.parent_generation_id || terminalView.delegation_id || terminalView.workflow_id) {
+        throw new LiveCoordinationAuthorityV3Error("lifecycle_not_human_facing");
+    }
+    const reopened = recordHookSignalV3({
+        coordRoot: input.coordRoot,
+        mode: route.mode,
+        signal: "session-start",
+        payload: { raw: {}, session_id: input.nativeSessionId },
+        adapter: terminal.adapter,
+        instance_id: instanceId,
+        producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+        build_id: route.build_id,
+        platform: livePlatformV3(),
+        session_start_derivation: "approved_lifecycle_reopen",
+    });
+    if (reopened.state !== "recorded" && reopened.state !== "already_started") {
+        throw new LiveCoordinationAuthorityV3Error(`generation_reopen_failed:${reopened.state}`);
+    }
+    const heartbeat = ensureLiveCoordinationHeartbeat(input.coordRoot, input.owner, input.nativeSessionId, terminal.adapter);
+    if (!heartbeat) {
+        throw new LiveCoordinationAuthorityV3Error("reopened_generation_materialization_failed");
+    }
+    return {
+        state: "reopened",
+        adapter: terminal.adapter,
+        prior_generation_id: terminal.generation_id,
+        generation_id: heartbeat.v3_generation_id,
+    };
+}
+export function recordLiveTaskChangeV3(input) {
+    liveCoordinationWriteModeV3(input.coordRoot);
+    const before = requireHeartbeat(input, input.subject ?? input.owner);
+    const cleared = input.task.length === 0;
+    const desired = {
+        ...before,
+        task: undefined,
+        v3_task_state: cleared ? "cleared" : "set",
+    };
+    // A task declaration is also per-turn ritual evidence. Record repeated
+    // declarations, including cleared -> cleared, even when the disposable view
+    // does not change. Otherwise a conversational Cursor remediation turn can
+    // run `set-task ""` exactly as instructed and still loop forever because no
+    // coord.task_changed event reaches the verdict window.
+    return recordLiveAuthority(input, "task-changed", {
+        native_observation_id: input.observationId ?? `task-${randomUUID()}`,
+        state: cleared ? "cleared" : "set",
+        ...(cleared ? {} : { task: input.task }),
+    }, before, desired, () => {
+        // The canonical event records only the privacy-safe set/cleared state.
+        // Task prose and its operator-facing suggested name live exclusively in
+        // this generation-bound disposable cache; they never enter the ledger.
+        if (!setTask(input.coordRoot, input.subject ?? input.owner, input.task)) {
+            throw new LiveCoordinationAuthorityV3Error("task_materialization_failed");
+        }
+    });
+}
+export function recordLiveLifecycleChangeV3(input) {
+    liveCoordinationWriteModeV3(input.coordRoot);
+    const subject = input.subject ?? input.owner;
+    const before = requireHeartbeat(input, subject);
+    const desired = {
+        ...before,
+        task_state: input.state,
+        task_state_reason: input.state === "active" ? undefined : input.reason,
+        ...(input.suggestedSessionName ? { suggested_session_name: input.suggestedSessionName } : {}),
+    };
+    if (authorityStateDigest(before) === authorityStateDigest(desired))
+        return { state: "unchanged" };
+    return recordLiveAuthority(input, "lifecycle-changed", {
+        native_observation_id: input.observationId ?? `lifecycle-${randomUUID()}`,
+        state: input.state,
+        ...(input.reason ? { reason_code: `operator_${input.state}` } : {}),
+    }, before, desired, () => {
+        if (!setLifecycleCache(input.coordRoot, subject, input.state, input.reason, input.suggestedSessionName)) {
+            throw new LiveCoordinationAuthorityV3Error("lifecycle_materialization_failed");
+        }
+    });
+}
+export function recordLiveClaimChangeV3(input) {
+    liveCoordinationWriteModeV3(input.coordRoot);
+    const subject = input.subject ?? input.owner;
+    const before = requireHeartbeat(input, subject);
+    const canonical = canonicalClaimPath(input.coordRoot, input.path);
+    const desiredFiles = input.operation === "acquired"
+        ? [
+            ...new Set([
+                ...(before.files_touched ?? []).map((path) => canonicalClaimPath(input.coordRoot, path)),
+                canonical,
+            ]),
+        ].sort()
+        : (before.files_touched ?? []).filter((path) => canonicalClaimPath(input.coordRoot, path) !== canonical);
+    const desired = { ...before, files_touched: desiredFiles };
+    if (authorityStateDigest(before) === authorityStateDigest(desired))
+        return { state: "unchanged" };
+    return recordLiveAuthority(input, "claim-changed", {
+        native_observation_id: input.observationId ?? `claim-${randomUUID()}`,
+        operation: input.operation,
+        target: canonical,
+        access: input.access ?? "write",
+    }, before, desired, () => {
+        const result = input.operation === "acquired"
+            ? acquireClaim(input.coordRoot, subject, canonical)
+            : releaseClaim(input.coordRoot, subject, canonical);
+        if (!result)
+            throw new LiveCoordinationAuthorityV3Error("claim_materialization_failed");
+    });
+}
+export function recordLiveIdentityChangeV3(input) {
+    liveCoordinationWriteModeV3(input.coordRoot);
+    const subject = input.subject ?? input.owner;
+    const before = requireHeartbeat(input, subject);
+    const desired = { ...before, name: input.name, agent_id: input.identityId };
+    if (authorityStateDigest(before) === authorityStateDigest(desired))
+        return { state: "unchanged" };
+    return recordLiveAuthority(input, "identity-attested", {
+        native_observation_id: input.observationId ?? `identity-${randomUUID()}`,
+        identity_id: input.identityId,
+        method: "operator_assumption",
+    }, before, desired, () => {
+        recordNameAssumption(input.coordRoot, subject, input.name, input.identityId, "session");
+        if (!setIdentityCache(input.coordRoot, subject, input.name, input.identityId)) {
+            throw new LiveCoordinationAuthorityV3Error("identity_materialization_failed");
+        }
+    });
+}
+function recordLiveAuthority(input, signal, observation, expected, desired, apply) {
+    const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
+    if (route.state === "blocked")
+        throw new LiveCoordinationAuthorityV3Error(route.reason);
+    const adapter = liveCoordinationAdapterV3(input.coordRoot, input.owner);
+    if (!adapter)
+        throw new LiveCoordinationAuthorityV3Error("actor_generation_missing");
+    const subject = input.subject ?? input.owner;
+    const result = recordAuthority({
+        coordRoot: input.coordRoot,
+        mode: route.mode,
+        signal,
+        observation,
+        adapter,
+        native_actor_session_id: input.nativeSessionId,
+        actor_instance_id: liveInstanceIdV3(input.owner),
+        subject_instance_id: liveInstanceIdV3(subject),
+        producer_id: LIVE_COORDINATION_V3_PRODUCER_ID,
+        build_id: route.build_id,
+        platform: livePlatformV3(),
+        expected_prior_state_digest: authorityStateDigest(expected),
+        desired_state_digest: authorityStateDigest(desired),
+        reconciler: {
+            readStateDigest: () => {
+                const heartbeat = readHeartbeat(input.coordRoot, subject);
+                if (!heartbeat || heartbeat.v3_generation_id !== expected.v3_generation_id) {
+                    throw new LiveCoordinationAuthorityV3Error(`heartbeat_generation_mismatch:${subject}`);
+                }
+                return authorityStateDigest(heartbeat);
+            },
+            apply: (_mutation) => apply(),
+        },
+    });
+    if (result.state === "gate_closed" || result.state === "generation_unavailable") {
+        throw new LiveCoordinationAuthorityV3Error(`${result.state}:${result.reason}`);
+    }
+    if (result.state === "pending_transaction") {
+        throw new LiveCoordinationAuthorityV3Error(`pending_transaction:${result.transaction_id}`);
+    }
+    return { state: "recorded", result };
+}
+function recordAuthority(input) {
+    return recordCoordinationAuthorityV3(input);
+}
+export function liveCoordinationWriteModeV3(coordRoot) {
+    const route = resolveLiveEventLedgerRouteV3(coordRoot);
+    if (route.state === "blocked")
+        throw new LiveCoordinationAuthorityV3Error(route.reason);
+    return route.mode;
+}
+function requireHeartbeat(input, owner) {
+    const heartbeat = ensureLiveCoordinationHeartbeat(input.coordRoot, owner, owner === input.owner ? input.nativeSessionId : owner, input.adapter);
+    if (!heartbeat)
+        throw new LiveCoordinationAuthorityV3Error(`heartbeat_missing:${owner}`);
+    return heartbeat;
+}
+function authorityStateDigest(heartbeat) {
+    return sha256V3(canonicalJsonV3({
+        instance_id: heartbeat.v3_instance_id ?? heartbeat.instance_id,
+        generation_id: heartbeat.v3_generation_id ?? null,
+        task_state: heartbeat.v3_task_state ?? (heartbeat.task ? "set" : "cleared"),
+        lifecycle_state: heartbeat.task_state ?? "active",
+        task_state_reason: heartbeat.task_state_reason ?? null,
+        files_touched: [...new Set(heartbeat.files_touched ?? [])].sort(),
+        identity_id: heartbeat.agent_id ?? null,
+        display_name: heartbeat.name ?? null,
+    }));
+}
+function canonicalClaimPath(coordRoot, path) {
+    return path.startsWith(`${coordRoot}/`) ? path.slice(coordRoot.length + 1) : path;
+}

package/dist/core/agents/live-lifecycle-v3.d.ts

@@ -0,0 +1,20 @@
+import type { Adapter } from "../adapter.js";
+import type { EventV3 } from "../events/v3/contract.js";
+export type LiveLifecycleObservationV3Result = {
+    state: "recorded";
+    event: EventV3;
+};
+interface LiveLifecycleObservationBaseV3 {
+    coordRoot: string;
+    owner: string;
+    nativeSessionId: string;
+    adapter: Adapter;
+    observedAt?: string;
+}
+export declare function recordLiveSweepObservationV3(input: LiveLifecycleObservationBaseV3 & {
+    observation: "stale_heartbeat" | "killed" | "unparseable_heartbeat" | "missing_timestamp";
+    ageMs: number;
+}): LiveLifecycleObservationV3Result;
+export declare function recordLiveResumeObservationV3(input: LiveLifecycleObservationBaseV3): LiveLifecycleObservationV3Result;
+export {};
+//# sourceMappingURL=live-lifecycle-v3.d.ts.map

package/dist/core/agents/live-lifecycle-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-lifecycle-v3.d.ts","sourceRoot":"","sources":["../../../src/core/agents/live-lifecycle-v3.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAaxD,MAAM,MAAM,gCAAgC,GAAG;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAErF,UAAU,8BAA8B;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,8BAA8B,GAAG;IACtC,WAAW,EAAE,iBAAiB,GAAG,QAAQ,GAAG,uBAAuB,GAAG,mBAAmB,CAAC;IAC1F,KAAK,EAAE,MAAM,CAAC;CACf,GACA,gCAAgC,CAOlC;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,8BAA8B,GACpC,gCAAgC,CAQlC"}