harnery 0.46.0 → 0.46.1

package/dist/core/agents/rules/claim-conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgBlD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CA4GjF"}
+{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgBlD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAmHjF"}

package/dist/core/agents/rules/claim-conflict.js

@@ -17,7 +17,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { adapterFromPlatform as sharedAdapterFromPlatform } from "../../adapter.js";
-import { recordLiveClaimChangeV3 } from "../live-authority-v3.js";
+import { resolveBinName } from "../../config.js";
+import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.js";
+import { LiveCoordinationAuthorityV3Error, recordLiveClaimChangeV3 } from "../live-authority-v3.js";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.js";
 const FRESHNESS_SECS = 600;
 /**
@@ -47,8 +49,9 @@ export function evaluateClaim(coordRoot, req) {
         // prune the claim from their heartbeat and allow the edit. Skips when the
         // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
         if (isFileCommittedClean(coordRoot, req.path)) {
-            if (!releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req)) {
-                return authorityUnavailable(req.path, "release the stale claim on");
+            const refused = releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req);
+            if (refused) {
+                return authorityUnavailable(coordRoot, req, req.path, "release the stale claim on", refused);
             }
             // Fall through to ordering check + allow.
         }
@@ -109,8 +112,9 @@ export function evaluateClaim(coordRoot, req) {
             // Every blocker is a finished (committed-clean) edit: prune them so they
             // stop constraining future acquisitions, then fall through to allow.
             for (const p of blockers) {
-                if (!releaseClaimThroughLedger(coordRoot, req.instance_id, p, req)) {
-                    return authorityUnavailable(p, "release the completed claim on");
+                const refused = releaseClaimThroughLedger(coordRoot, req.instance_id, p, req);
+                if (refused) {
+                    return authorityUnavailable(coordRoot, req, p, "release the completed claim on", refused);
                 }
             }
         }
@@ -118,9 +122,9 @@ export function evaluateClaim(coordRoot, req) {
     // Acquire the claim: atomic check-and-set. Adds req.path to my
     // files_touched if not already present.
     if (req.mode !== "read") {
-        if (!acquireClaimThroughLedger(coordRoot, req)) {
-            return authorityUnavailable(req.path, "acquire");
-        }
+        const refused = acquireClaimThroughLedger(coordRoot, req);
+        if (refused)
+            return authorityUnavailable(coordRoot, req, req.path, "acquire", refused);
     }
     return { allow: true, exit_code: 0, rule: "claim.pass" };
 }
@@ -205,6 +209,7 @@ function isFileCommittedClean(coordRoot, relPath) {
         return false;
     }
 }
+/** Returns null when the ledger recorded the claim, else the refusal reason. */
 function acquireClaimThroughLedger(coordRoot, req) {
     const owner = readPeers(coordRoot).find((peer) => peer.instance_id === req.instance_id);
     try {
@@ -217,10 +222,10 @@ function acquireClaimThroughLedger(coordRoot, req) {
             path: req.path,
             access: "write",
         });
-        return true;
+        return null;
     }
-    catch {
-        return false;
+    catch (error) {
+        return refusalReason(error);
     }
 }
 function releaseClaimThroughLedger(coordRoot, subjectInstanceId, relPath, actor) {
@@ -236,17 +241,32 @@ function releaseClaimThroughLedger(coordRoot, subjectInstanceId, relPath, actor)
             path: relPath,
             access: "write",
         });
-        return true;
+        return null;
     }
-    catch {
-        return false;
+    catch (error) {
+        return refusalReason(error);
     }
 }
-function authorityUnavailable(path, operation) {
+function refusalReason(error) {
+    if (error instanceof LiveCoordinationAuthorityV3Error)
+        return error.reason;
+    return error instanceof Error ? error.message : String(error);
+}
+function authorityUnavailable(coordRoot, req, path, operation, refusal) {
+    // The ledger's own reason is the only evidence of why a healthy-looking
+    // session cannot claim; a generic message sent agents to diagnose the wrong
+    // layer, so keep the reason in the verdict and in a durable diagnostic.
+    writeProducerDiagnosticV3(coordRoot, "claim_authority_refused", {
+        instance_id: req.instance_id,
+        operation,
+        reason: refusal,
+    });
     return {
         allow: false,
         exit_code: 2,
         rule: "claim.authority_unavailable",
-        reason: `Cannot safely ${operation} ${path}; V3 authority is unavailable.`,
+        reason: `Cannot safely ${operation} ${path}; the coordination ledger refused the claim ` +
+            `(${refusal}). Run \`${resolveBinName(coordRoot)} agents health\` and retry; if health ` +
+            "is safe, the refusal reason above names the session state that blocked it.",
     };
 }

package/dist/core/agents/rules/stop-hook.d.ts

@@ -26,6 +26,12 @@ export interface StopHookRequest {
     session_name_observation_unavailable?: boolean;
     bypass?: boolean;
     workflow_child?: boolean;
+    /**
+     * Claude Code moved this session's foreground command into the background
+     * and has not yet reported it finished. Finalization cannot pass until it
+     * does, so status and reply-box demands wait for the notification turn.
+     */
+    pending_background_handoff?: boolean;
 }
 export declare const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
 export declare function evaluateStopHook(coordRoot: string, req: StopHookRequest): VerdictResult;

package/dist/core/agents/rules/stop-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stop-hook.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/stop-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAM3D,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iFAAiF;IACjF,oCAAoC,CAAC,EAAE,OAAO,CAAC;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAInE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,aAAa,CA6BvF;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,aAAa,CAiIf"}
+{"version":3,"file":"stop-hook.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/stop-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAM3D,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iFAAiF;IACjF,oCAAoC,CAAC,EAAE,OAAO,CAAC;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAInE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,aAAa,CA6BvF;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,aAAa,CA2If"}

package/dist/core/agents/rules/stop-hook.js

@@ -101,6 +101,8 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
     // Pure prose turns keep the human-visible acknowledgement but do not require
     // task or final-status mutations. This preserves the pre-V3 policy exactly.
     if (!usedTool) {
+        if (!ackPresent && req.pending_background_handoff)
+            return backgroundHandoffDeferred();
         if (!ackPresent)
             return withCycleAnchor(ackBlock(), cycleAnchor);
         return {
@@ -133,11 +135,28 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
             pending.push(sessionNameBlock(coordRoot, req.instance_id));
         }
     }
-    const blocked = mergeStopBlocks(pending);
+    // A status check run now would refuse on the in-flight commit and a box
+    // cannot be issued without it, so bouncing only loops until the task ends.
+    // Task and naming evidence do not depend on the task and stay enforced.
+    const enforced = req.pending_background_handoff
+        ? pending.filter((block) => block.rule !== "stop-hook.rule_1_3" && block.rule !== "stop-hook.rule_2_3")
+        : pending;
+    const blocked = mergeStopBlocks(enforced);
     if (blocked)
         return withCycleAnchor(blocked, cycleAnchor);
+    if (enforced.length < pending.length)
+        return backgroundHandoffDeferred();
     return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
+function backgroundHandoffDeferred() {
+    return {
+        allow: true,
+        exit_code: 0,
+        rule: "stop-hook.background_handoff_deferred",
+        reason: "a command Claude Code moved to the background is still running; status and reply-box " +
+            "evidence are required on the turn its completion notification starts",
+    };
+}
 function unconditionalVerdict(req) {
     if (req.bypass) {
         return {

package/dist/core/hooks/cli.js

@@ -55,7 +55,7 @@ import { beginHookHealth, observeHookDebug, observeHookError, writeHookHealthCom
 import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
-import { inspectSessionNameDisplayImmediately, scanAssistantStatusBoxPresent, scanStatusBoxPresent, scanTranscriptRuntime, } from "./resolve/transcript.js";
+import { inspectSessionNameDisplayImmediately, scanAssistantStatusBoxPresent, scanPendingBackgroundHandoffs, scanStatusBoxPresent, scanTranscriptRuntime, } from "./resolve/transcript.js";
 import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.js";
 import { sessionNamePresence } from "./session-name-presence.js";
 import { shellCommitTreeReason } from "./shell-commit-tree.js";
@@ -1222,6 +1222,14 @@ async function handleStop(run) {
     catch (err) {
         logError(coordRoot, err, { phase: "stop-presence" });
     }
+    // Claude Code may move a running foreground command (often the agent's own
+    // commit and push) into the background to deliver a user message. Until it
+    // reports back, finalization cannot pass, so the verdict defers the status
+    // demands instead of bouncing the agent in a loop.
+    const pendingBackgroundHandoffs = adapter === "claude-code"
+        ? scanPendingBackgroundHandoffs(payload?.transcript_path ??
+            behavior.discoverTranscript?.(payload?.session_id ?? sessionId))
+        : [];
     // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
     // rule lives in Harnery. agent-hook already emitted this turn.completed
     // with privacy-safe ritual observations, so the evidence is in the stream.
@@ -1235,7 +1243,15 @@ async function handleStop(run) {
         session_name_observation_unavailable: typeof data.session_name_unavailable_reason === "string",
         bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
         workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
+        pending_background_handoff: pendingBackgroundHandoffs.length > 0,
     });
+    if (verdict.rule === "stop-hook.background_handoff_deferred") {
+        appendDebug(coordRoot, {
+            ...debugBase,
+            effect: "stop-deferred-background-handoff",
+            background_task_ids: pendingBackgroundHandoffs,
+        });
+    }
     if (!verdict.allow) {
         // Backstop for sessions whose evidence can never land (e.g. a headless
         // child whose status command resolves to a different owner): after
@@ -1270,6 +1286,13 @@ async function handleStop(run) {
     // until the adapter has committed turn.completed above. Reconcile only
     // when such a request exists; any later real work cancels it in the
     // finalizer instead of being terminated underneath the agent.
+    // A deferred stop proves nothing about finalization; an explicit end must
+    // wait for the turn that reports the background task's result.
+    if (verdict.rule === "stop-hook.background_handoff_deferred") {
+        if (behavior.runtimeContextRetry)
+            scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+        return undefined;
+    }
     try {
         const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import("../agents/session-finalizer-v3.js");
         if (hasPendingExplicitSessionEndV3(coordRoot)) {

package/dist/core/hooks/resolve/transcript.d.ts

@@ -33,6 +33,18 @@ export declare function scanAssistantTextIncludes(transcriptPath: string | undef
  * from the adapter's completed assistant response.
  */
 export declare function scanAssistantStatusBoxPresent(transcriptPath: string | undefined, lastAssistantMessage: string | undefined): boolean;
+/** A handoff older than this no longer defers Stop, so a lost notification cannot disable the ritual. */
+export declare const BACKGROUND_HANDOFF_MAX_AGE_MS: number;
+/**
+ * Claude Code background tasks it moved off the foreground on its own (to
+ * deliver a mid-command user message) that have not yet posted a
+ * `<task-notification>`. Only the structured `toolUseResult` fields written by
+ * Claude Code open a handoff; the agent cannot forge them through tool output.
+ * Any later notification text naming the task closes it, so a spoofed
+ * notification can only make Stop stricter. A command the agent chose to
+ * background (`run_in_background`) or a Monitor opens nothing.
+ */
+export declare function scanPendingBackgroundHandoffs(transcriptPath: string | undefined, nowMs?: number): string[];
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export declare function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined;
 /**

package/dist/core/hooks/resolve/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,2BAA2B,wBAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAKT;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IACE,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,GAAG,wBAAwB,CAAC;CAClF,CAAC;AAEN;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CAqD9B;AAgBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAiBpB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,2BAA2B,wBAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAKT;AAED,yGAAyG;AACzG,eAAO,MAAM,6BAA6B,QAAiB,CAAC;AAQ5D;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,KAAK,GAAE,MAAmB,GACzB,MAAM,EAAE,CAsCV;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IACE,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,GAAG,wBAAwB,CAAC;CAClF,CAAC;AAEN;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CAqD9B;AAgBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAiBpB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}

package/dist/core/hooks/resolve/transcript.js

@@ -88,6 +88,60 @@ export function scanAssistantStatusBoxPresent(transcriptPath, lastAssistantMessa
     return (scanAssistantTextIncludes(transcriptPath, ASSISTANT_STATUS_BOX_PREFIX) ||
         lastAssistantMessage?.includes(ASSISTANT_STATUS_BOX_PREFIX) === true);
 }
+/** A handoff older than this no longer defers Stop, so a lost notification cannot disable the ritual. */
+export const BACKGROUND_HANDOFF_MAX_AGE_MS = 30 * 60 * 1000;
+/**
+ * Claude Code interleaves request-capture rows of several hundred KB each, so
+ * the 256KB status-box window can lose a handoff written a minute earlier.
+ */
+const BACKGROUND_HANDOFF_TAIL_BYTES = 8 * 1024 * 1024;
+/**
+ * Claude Code background tasks it moved off the foreground on its own (to
+ * deliver a mid-command user message) that have not yet posted a
+ * `<task-notification>`. Only the structured `toolUseResult` fields written by
+ * Claude Code open a handoff; the agent cannot forge them through tool output.
+ * Any later notification text naming the task closes it, so a spoofed
+ * notification can only make Stop stricter. A command the agent chose to
+ * background (`run_in_background`) or a Monitor opens nothing.
+ */
+export function scanPendingBackgroundHandoffs(transcriptPath, nowMs = Date.now()) {
+    const readablePath = resolveTranscriptPath(transcriptPath);
+    if (!readablePath)
+        return [];
+    let size;
+    try {
+        size = statSync(readablePath).size;
+    }
+    catch {
+        return [];
+    }
+    const text = readRange(readablePath, Math.max(0, size - BACKGROUND_HANDOFF_TAIL_BYTES), size);
+    if (!text)
+        return [];
+    const opened = new Map();
+    for (const line of text.split("\n")) {
+        // Request-capture rows echo the same text; the row-type check below keeps
+        // only Claude Code's own top-level tool-result rows.
+        if (line.includes("backgroundedToDeliverMessage")) {
+            const row = parseTranscriptRow(line);
+            const result = row?.toolUseResult;
+            if (row?.type === "user" &&
+                result?.backgroundedToDeliverMessage === true &&
+                typeof result.backgroundTaskId === "string" &&
+                result.backgroundTaskId) {
+                opened.set(result.backgroundTaskId, Date.parse(String(row.timestamp)));
+            }
+        }
+        if (line.includes("task-notification")) {
+            for (const match of line.matchAll(/<task-id>([^<]+)<\/task-id>/g)) {
+                opened.delete(match[1]);
+            }
+        }
+    }
+    return [...opened]
+        .filter(([, at]) => Number.isFinite(at) && nowMs - at <= BACKGROUND_HANDOFF_MAX_AGE_MS)
+        .map(([id]) => id);
+}
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath) {
     const readablePath = resolveTranscriptPath(transcriptPath);

package/package.json

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

package/src/core/agents/rules/claim-conflict.ts

@@ -18,7 +18,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { adapterFromPlatform as sharedAdapterFromPlatform } from "../../adapter.ts";
-import { recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
+import { resolveBinName } from "../../config.ts";
+import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.ts";
+import { LiveCoordinationAuthorityV3Error, recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 
 const FRESHNESS_SECS = 600;
@@ -82,8 +84,15 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
     // prune the claim from their heartbeat and allow the edit. Skips when the
     // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
     if (isFileCommittedClean(coordRoot, req.path)) {
-      if (!releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req)) {
-        return authorityUnavailable(req.path, "release the stale claim on");
+      const refused = releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req);
+      if (refused) {
+        return authorityUnavailable(
+          coordRoot,
+          req,
+          req.path,
+          "release the stale claim on",
+          refused,
+        );
       }
       // Fall through to ordering check + allow.
     } else {
@@ -146,8 +155,9 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
       // Every blocker is a finished (committed-clean) edit: prune them so they
       // stop constraining future acquisitions, then fall through to allow.
       for (const p of blockers) {
-        if (!releaseClaimThroughLedger(coordRoot, req.instance_id, p, req)) {
-          return authorityUnavailable(p, "release the completed claim on");
+        const refused = releaseClaimThroughLedger(coordRoot, req.instance_id, p, req);
+        if (refused) {
+          return authorityUnavailable(coordRoot, req, p, "release the completed claim on", refused);
         }
       }
     }
@@ -156,9 +166,8 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
   // Acquire the claim: atomic check-and-set. Adds req.path to my
   // files_touched if not already present.
   if (req.mode !== "read") {
-    if (!acquireClaimThroughLedger(coordRoot, req)) {
-      return authorityUnavailable(req.path, "acquire");
-    }
+    const refused = acquireClaimThroughLedger(coordRoot, req);
+    if (refused) return authorityUnavailable(coordRoot, req, req.path, "acquire", refused);
   }
 
   return { allow: true, exit_code: 0, rule: "claim.pass" };
@@ -242,7 +251,8 @@ function isFileCommittedClean(coordRoot: string, relPath: string): boolean {
   }
 }
 
-function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): boolean {
+/** Returns null when the ledger recorded the claim, else the refusal reason. */
+function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): string | null {
   const owner = readPeers(coordRoot).find((peer) => peer.instance_id === req.instance_id);
   try {
     recordLiveClaimChangeV3({
@@ -254,9 +264,9 @@ function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): boolea
       path: req.path,
       access: "write",
     });
-    return true;
-  } catch {
-    return false;
+    return null;
+  } catch (error) {
+    return refusalReason(error);
   }
 }
 
@@ -265,7 +275,7 @@ function releaseClaimThroughLedger(
   subjectInstanceId: string,
   relPath: string,
   actor: ClaimRequest,
-): boolean {
+): string | null {
   const owner = readPeers(coordRoot).find((peer) => peer.instance_id === actor.instance_id);
   try {
     recordLiveClaimChangeV3({
@@ -278,17 +288,39 @@ function releaseClaimThroughLedger(
       path: relPath,
       access: "write",
     });
-    return true;
-  } catch {
-    return false;
+    return null;
+  } catch (error) {
+    return refusalReason(error);
   }
 }
 
-function authorityUnavailable(path: string, operation: string): VerdictResult {
+function refusalReason(error: unknown): string {
+  if (error instanceof LiveCoordinationAuthorityV3Error) return error.reason;
+  return error instanceof Error ? error.message : String(error);
+}
+
+function authorityUnavailable(
+  coordRoot: string,
+  req: ClaimRequest,
+  path: string,
+  operation: string,
+  refusal: string,
+): VerdictResult {
+  // The ledger's own reason is the only evidence of why a healthy-looking
+  // session cannot claim; a generic message sent agents to diagnose the wrong
+  // layer, so keep the reason in the verdict and in a durable diagnostic.
+  writeProducerDiagnosticV3(coordRoot, "claim_authority_refused", {
+    instance_id: req.instance_id,
+    operation,
+    reason: refusal,
+  });
   return {
     allow: false,
     exit_code: 2,
     rule: "claim.authority_unavailable",
-    reason: `Cannot safely ${operation} ${path}; V3 authority is unavailable.`,
+    reason:
+      `Cannot safely ${operation} ${path}; the coordination ledger refused the claim ` +
+      `(${refusal}). Run \`${resolveBinName(coordRoot)} agents health\` and retry; if health ` +
+      "is safe, the refusal reason above names the session state that blocked it.",
   };
 }

package/src/core/agents/rules/stop-hook.ts

@@ -36,6 +36,12 @@ export interface StopHookRequest {
   session_name_observation_unavailable?: boolean;
   bypass?: boolean;
   workflow_child?: boolean;
+  /**
+   * Claude Code moved this session's foreground command into the background
+   * and has not yet reported it finished. Finalization cannot pass until it
+   * does, so status and reply-box demands wait for the notification turn.
+   */
+  pending_background_handoff?: boolean;
 }
 
 export const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
@@ -170,6 +176,7 @@ export function evaluateStopHookV3Events(
   // Pure prose turns keep the human-visible acknowledgement but do not require
   // task or final-status mutations. This preserves the pre-V3 policy exactly.
   if (!usedTool) {
+    if (!ackPresent && req.pending_background_handoff) return backgroundHandoffDeferred();
     if (!ackPresent) return withCycleAnchor(ackBlock(), cycleAnchor);
     return {
       allow: true,
@@ -203,12 +210,32 @@ export function evaluateStopHookV3Events(
     }
   }
 
-  const blocked = mergeStopBlocks(pending);
+  // A status check run now would refuse on the in-flight commit and a box
+  // cannot be issued without it, so bouncing only loops until the task ends.
+  // Task and naming evidence do not depend on the task and stay enforced.
+  const enforced = req.pending_background_handoff
+    ? pending.filter(
+        (block) => block.rule !== "stop-hook.rule_1_3" && block.rule !== "stop-hook.rule_2_3",
+      )
+    : pending;
+  const blocked = mergeStopBlocks(enforced);
   if (blocked) return withCycleAnchor(blocked, cycleAnchor);
+  if (enforced.length < pending.length) return backgroundHandoffDeferred();
 
   return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
 
+function backgroundHandoffDeferred(): VerdictResult {
+  return {
+    allow: true,
+    exit_code: 0,
+    rule: "stop-hook.background_handoff_deferred",
+    reason:
+      "a command Claude Code moved to the background is still running; status and reply-box " +
+      "evidence are required on the turn its completion notification starts",
+  };
+}
+
 function unconditionalVerdict(req: StopHookRequest): VerdictResult | undefined {
   if (req.bypass) {
     return {

package/src/core/hooks/cli.ts

@@ -139,6 +139,7 @@ import type { SessionNameDisplayInspection } from "./resolve/transcript.ts";
 import {
   inspectSessionNameDisplayImmediately,
   scanAssistantStatusBoxPresent,
+  scanPendingBackgroundHandoffs,
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
@@ -1506,6 +1507,18 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
     logError(coordRoot, err, { phase: "stop-presence" });
   }
 
+  // Claude Code may move a running foreground command (often the agent's own
+  // commit and push) into the background to deliver a user message. Until it
+  // reports back, finalization cannot pass, so the verdict defers the status
+  // demands instead of bouncing the agent in a loop.
+  const pendingBackgroundHandoffs =
+    adapter === "claude-code"
+      ? scanPendingBackgroundHandoffs(
+          payload?.transcript_path ??
+            behavior.discoverTranscript?.(payload?.session_id ?? sessionId),
+        )
+      : [];
+
   // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
   // rule lives in Harnery. agent-hook already emitted this turn.completed
   // with privacy-safe ritual observations, so the evidence is in the stream.
@@ -1519,7 +1532,15 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
     session_name_observation_unavailable: typeof data.session_name_unavailable_reason === "string",
     bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
     workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
+    pending_background_handoff: pendingBackgroundHandoffs.length > 0,
   });
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    appendDebug(coordRoot, {
+      ...debugBase,
+      effect: "stop-deferred-background-handoff",
+      background_task_ids: pendingBackgroundHandoffs,
+    });
+  }
   if (!verdict.allow) {
     // Backstop for sessions whose evidence can never land (e.g. a headless
     // child whose status command resolves to a different owner): after
@@ -1553,6 +1574,12 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
   // until the adapter has committed turn.completed above. Reconcile only
   // when such a request exists; any later real work cancels it in the
   // finalizer instead of being terminated underneath the agent.
+  // A deferred stop proves nothing about finalization; an explicit end must
+  // wait for the turn that reports the background task's result.
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    if (behavior.runtimeContextRetry) scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+    return undefined;
+  }
   try {
     const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import(
       "../agents/session-finalizer-v3.ts"

package/src/core/hooks/resolve/transcript.ts

@@ -94,6 +94,67 @@ export function scanAssistantStatusBoxPresent(
   );
 }
 
+/** A handoff older than this no longer defers Stop, so a lost notification cannot disable the ritual. */
+export const BACKGROUND_HANDOFF_MAX_AGE_MS = 30 * 60 * 1000;
+
+/**
+ * Claude Code interleaves request-capture rows of several hundred KB each, so
+ * the 256KB status-box window can lose a handoff written a minute earlier.
+ */
+const BACKGROUND_HANDOFF_TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Claude Code background tasks it moved off the foreground on its own (to
+ * deliver a mid-command user message) that have not yet posted a
+ * `<task-notification>`. Only the structured `toolUseResult` fields written by
+ * Claude Code open a handoff; the agent cannot forge them through tool output.
+ * Any later notification text naming the task closes it, so a spoofed
+ * notification can only make Stop stricter. A command the agent chose to
+ * background (`run_in_background`) or a Monitor opens nothing.
+ */
+export function scanPendingBackgroundHandoffs(
+  transcriptPath: string | undefined,
+  nowMs: number = Date.now(),
+): string[] {
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return [];
+  let size: number;
+  try {
+    size = statSync(readablePath).size;
+  } catch {
+    return [];
+  }
+  const text = readRange(readablePath, Math.max(0, size - BACKGROUND_HANDOFF_TAIL_BYTES), size);
+  if (!text) return [];
+  const opened = new Map<string, number>();
+  for (const line of text.split("\n")) {
+    // Request-capture rows echo the same text; the row-type check below keeps
+    // only Claude Code's own top-level tool-result rows.
+    if (line.includes("backgroundedToDeliverMessage")) {
+      const row = parseTranscriptRow(line);
+      const result = row?.toolUseResult as
+        | { backgroundTaskId?: unknown; backgroundedToDeliverMessage?: unknown }
+        | undefined;
+      if (
+        row?.type === "user" &&
+        result?.backgroundedToDeliverMessage === true &&
+        typeof result.backgroundTaskId === "string" &&
+        result.backgroundTaskId
+      ) {
+        opened.set(result.backgroundTaskId, Date.parse(String(row.timestamp)));
+      }
+    }
+    if (line.includes("task-notification")) {
+      for (const match of line.matchAll(/<task-id>([^<]+)<\/task-id>/g)) {
+        opened.delete(match[1]!);
+      }
+    }
+  }
+  return [...opened]
+    .filter(([, at]) => Number.isFinite(at) && nowMs - at <= BACKGROUND_HANDOFF_MAX_AGE_MS)
+    .map(([id]) => id);
+}
+
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);