@deftai/directive-core 0.108.0 → 0.109.0

package/dist/scm/gh-rest.d.ts

@@ -1,4 +1,5 @@
-import { resolveBinary } from "./binary.js";
+import { type SpawnSyncOptions } from "node:child_process";
+import { type WhichFn } from "./binary.js";
 export declare const DEFAULT_TIMEOUT_S = 60;
 /** Raised when the `"owner/repo"` argument is malformed. */
 export declare class InvalidRepoError extends Error {
@@ -11,35 +12,47 @@ export declare class GhRestError extends Error {
     readonly endpoint: string;
     readonly payload: Record<string, unknown> | null;
     readonly hint: string;
+    readonly binary: string;
     constructor(options: {
         stderr: string;
         exitCode: number;
         endpoint: string;
         payload: Record<string, unknown> | null;
         hint?: string;
+        binary?: string;
     });
 }
-export type RunGhApiFn = (args: readonly string[], options?: {
-    timeout?: number;
-    whichFn?: Parameters<typeof resolveBinary>[0];
-}) => {
+export type GhSpawnResult = {
+    readonly status: number | null;
+    readonly stdout?: string | Buffer | null;
+    readonly stderr?: string | Buffer | null;
+    readonly error?: {
+        readonly message?: string;
+        readonly code?: string;
+    };
+};
+export type GhSpawnFn = (command: string, args: readonly string[], options: SpawnSyncOptions) => GhSpawnResult;
+export type GhApiProcess = {
     returncode: number;
     stdout: string;
     stderr: string;
+    binary?: string;
 };
+export type RunGhApiFn = (args: readonly string[], options?: {
+    timeout?: number;
+    whichFn?: WhichFn;
+    spawnFn?: GhSpawnFn;
+}) => GhApiProcess;
 /** Single subprocess seam invoked by every helper. */
 export declare function runGhApi(args: readonly string[], options?: {
     timeout?: number;
-    whichFn?: Parameters<typeof resolveBinary>[0];
-}): {
-    returncode: number;
-    stdout: string;
-    stderr: string;
-};
+    whichFn?: WhichFn;
+    spawnFn?: GhSpawnFn;
+}): GhApiProcess;
 export declare function splitRepo(repo: string): [string, string];
 export interface GhRestSeams {
     readonly runGhApiFn?: RunGhApiFn;
-    readonly whichFn?: Parameters<typeof resolveBinary>[0];
+    readonly whichFn?: WhichFn;
 }
 /** `GET /repos/{owner}/{repo}/issues/{n}` -- read a single issue. */
 export declare function restIssueView(repo: string, n: number, seams?: GhRestSeams): Record<string, unknown>;

package/dist/scm/gh-rest.js

@@ -3,8 +3,10 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
-import { resolveBinary } from "./binary.js";
+import { defaultWhich } from "./binary.js";
+import { classifyScmArgv, resolveBinaryForRole } from "./call-shape.js";
 import { pyRepr } from "./py-format.js";
+import { classifySpawnStatus, formatScmSpawnDiagnostic, isAvailabilitySpawnFailure, } from "./spawn-status.js";
 export const DEFAULT_TIMEOUT_S = 60;
 /** Raised when the `"owner/repo"` argument is malformed. */
 export class InvalidRepoError extends Error {
@@ -23,10 +25,16 @@ export class GhRestError extends Error {
     endpoint;
     payload;
     hint;
+    binary;
     constructor(options) {
         const hint = options.hint ?? "";
-        let msg = `gh api failed: endpoint=${pyRepr(options.endpoint)} ` +
-            `exit=${options.exitCode} stderr=${pyRepr(options.stderr)}`;
+        const binary = options.binary ?? "gh";
+        const statusClass = classifySpawnStatus(options.exitCode);
+        let msg = `${binary} api failed: endpoint=${pyRepr(options.endpoint)} ` + `exit=${options.exitCode}`;
+        if (statusClass !== `exit ${options.exitCode}`) {
+            msg += ` (${statusClass})`;
+        }
+        msg += ` stderr=${pyRepr(options.stderr)}`;
         if (hint.length > 0) {
             msg += `; hint: ${hint}`;
         }
@@ -37,30 +45,70 @@ export class GhRestError extends Error {
         this.endpoint = options.endpoint;
         this.payload = options.payload;
         this.hint = hint;
+        this.binary = binary;
+    }
+}
+function defaultGhSpawn(command, args, options) {
+    return spawnSync(command, [...args], options);
+}
+function finalizeGhApiResult(binary, result) {
+    const rawStderr = typeof result.stderr === "string" ? result.stderr : "";
+    let stderr = rawStderr;
+    if (result.status === null && result.error && stderr.trim().length === 0) {
+        stderr = result.error.message ?? "";
     }
+    if (isAvailabilitySpawnFailure({
+        status: result.status,
+        error: result.error,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: rawStderr,
+    }) &&
+        stderr.trim().length === 0) {
+        stderr = formatScmSpawnDiagnostic(binary, result.status, stderr, result.error);
+    }
+    return {
+        returncode: result.status ?? 1,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr,
+        binary,
+        rawStderr,
+        rawStatus: result.status,
+        error: result.error,
+    };
 }
 /** Single subprocess seam invoked by every helper. */
 export function runGhApi(args, options = {}) {
-    const binary = resolveBinary(options.whichFn);
+    const whichFn = options.whichFn ?? defaultWhich;
+    const spawnFn = options.spawnFn ?? defaultGhSpawn;
+    const role = classifyScmArgv("api", args);
+    let binary = resolveBinaryForRole(role, whichFn);
     const timeoutMs = options.timeout !== undefined ? Math.round(options.timeout * 1000) : DEFAULT_TIMEOUT_S * 1000;
-    const result = spawnSync(binary, ["api", ...args], {
+    const spawnOpts = {
         encoding: "utf8",
         timeout: timeoutMs,
         env: process.env,
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stderr = typeof result.stderr === "string" ? result.stderr : "";
-    // A spawn-level failure (e.g. ENOBUFS when stdout exceeds maxBuffer) yields a
-    // null status and empty stderr; surface error.message so the GhRestError that
-    // wraps this never reports a blank reason (#1867).
-    if (result.status === null && result.error && stderr.trim().length === 0) {
-        stderr = result.error.message;
+    };
+    const spawnOnce = (bin) => finalizeGhApiResult(bin, spawnFn(bin, ["api", ...args], spawnOpts));
+    let first = spawnOnce(binary);
+    if (role === "cached-get" &&
+        binary === "ghx" &&
+        isAvailabilitySpawnFailure({
+            status: first.rawStatus,
+            error: first.error,
+            stdout: first.stdout,
+            stderr: first.rawStderr,
+        }) &&
+        whichFn("gh") !== null) {
+        binary = "gh";
+        first = spawnOnce(binary);
     }
     return {
-        returncode: result.status ?? 1,
-        stdout: typeof result.stdout === "string" ? result.stdout : "",
-        stderr,
+        returncode: first.returncode,
+        stdout: first.stdout,
+        stderr: first.stderr,
+        binary,
     };
 }
 export function splitRepo(repo) {
@@ -83,6 +131,7 @@ function execApi(args, options) {
             endpoint: options.endpoint,
             payload: options.payload,
             hint: options.hint ?? "",
+            binary: result.binary ?? "gh",
         });
     }
     const stdout = result.stdout.trim();
@@ -393,6 +442,7 @@ export function restIssueListOpenInventory(repo, seams = {}) {
             endpoint,
             payload: null,
             hint: "verify gh auth and core REST quota; open-issue inventory must be complete",
+            binary: result.binary ?? "gh",
         });
     }
     const stdout = result.stdout.trim();

package/dist/scm/index.d.ts

@@ -2,6 +2,7 @@ export * from "./argv.js";
 export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
+export * from "./call-shape.js";
 export * from "./constants.js";
 export * from "./design-critique-chip.js";
 export * from "./errors.js";
@@ -10,4 +11,5 @@ export * from "./main.js";
 export * from "./py-format.js";
 export * from "./readiness.js";
 export * from "./rest-dispatch.js";
+export * from "./spawn-status.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scm/index.js

@@ -2,6 +2,7 @@ export * from "./argv.js";
 export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
+export * from "./call-shape.js";
 export * from "./constants.js";
 export * from "./design-critique-chip.js";
 export * from "./errors.js";
@@ -10,4 +11,5 @@ export * from "./main.js";
 export * from "./py-format.js";
 export * from "./readiness.js";
 export * from "./rest-dispatch.js";
+export * from "./spawn-status.js";
 //# sourceMappingURL=index.js.map

package/dist/scm/spawn-status.d.ts

@@ -0,0 +1,33 @@
+import type { WhichFn } from "./binary.js";
+import type { ScmBinaryRole } from "./call-shape.js";
+/** Windows NTSTATUS STATUS_DLL_INIT_FAILED (#3737). Unsigned and signed 32-bit. */
+export declare const STATUS_DLL_INIT_FAILED = 3221225794;
+export declare function unsignedExitStatus(status: number): number;
+export declare function classifySpawnStatus(status: number | null | undefined, error?: {
+    readonly message?: string;
+    readonly code?: string;
+}): string;
+export declare function isAvailabilitySpawnFailure(result: {
+    readonly status: number | null | undefined;
+    readonly error?: {
+        readonly message?: string;
+        readonly code?: string;
+    };
+    readonly stdout?: string;
+    readonly stderr?: string;
+}): boolean;
+export declare function formatScmSpawnDiagnostic(binary: string, status: number | null | undefined, stderr: string, error?: {
+    readonly message?: string;
+    readonly code?: string;
+}): string;
+/** Return `gh` when a cached-get ghx spawn failed and live gh is on PATH. */
+export declare function ghxSpawnFallbackBinary(role: ScmBinaryRole, invoked: string, whichFn: WhichFn, failure: {
+    readonly status: number | null | undefined;
+    readonly error?: {
+        readonly message?: string;
+        readonly code?: string;
+    };
+    readonly stdout?: string;
+    readonly stderr?: string;
+}): string | null;
+//# sourceMappingURL=spawn-status.d.ts.map

package/dist/scm/spawn-status.js

@@ -0,0 +1,53 @@
+/** Windows NTSTATUS STATUS_DLL_INIT_FAILED (#3737). Unsigned and signed 32-bit. */
+export const STATUS_DLL_INIT_FAILED = 0xc0000142;
+const STATUS_DLL_INIT_FAILED_SIGNED = -1073741502;
+export function unsignedExitStatus(status) {
+    return status >>> 0;
+}
+export function classifySpawnStatus(status, error) {
+    if (typeof status !== "number") {
+        if (typeof error?.code === "string" && error.code.length > 0) {
+            return error.code;
+        }
+        if (typeof error?.message === "string" && error.message.trim().length > 0) {
+            return error.message.trim();
+        }
+        return "spawn-failed";
+    }
+    const unsigned = unsignedExitStatus(status);
+    if (unsigned === STATUS_DLL_INIT_FAILED || status === STATUS_DLL_INIT_FAILED_SIGNED) {
+        return "0xC0000142 STATUS_DLL_INIT_FAILED";
+    }
+    if (unsigned >= 0xc0000000) {
+        return `0x${unsigned.toString(16).toUpperCase()}`;
+    }
+    return `exit ${status}`;
+}
+export function isAvailabilitySpawnFailure(result) {
+    if (result.error !== undefined) {
+        return true;
+    }
+    if (typeof result.status !== "number") {
+        return true;
+    }
+    const unsigned = unsignedExitStatus(result.status);
+    const emptyOut = (result.stdout ?? "").trim().length === 0 && (result.stderr ?? "").trim().length === 0;
+    return (emptyOut &&
+        (unsigned === STATUS_DLL_INIT_FAILED || result.status === STATUS_DLL_INIT_FAILED_SIGNED));
+}
+export function formatScmSpawnDiagnostic(binary, status, stderr, error) {
+    const cls = classifySpawnStatus(status, error);
+    const err = stderr.trim();
+    if (err.length > 0) {
+        return `${binary} failed (${cls}): ${err}`;
+    }
+    return `${binary} failed (${cls}); stderr empty`;
+}
+/** Return `gh` when a cached-get ghx spawn failed and live gh is on PATH. */
+export function ghxSpawnFallbackBinary(role, invoked, whichFn, failure) {
+    if (role !== "cached-get" || invoked !== "ghx" || whichFn("gh") === null) {
+        return null;
+    }
+    return isAvailabilitySpawnFailure(failure) ? "gh" : null;
+}
+//# sourceMappingURL=spawn-status.js.map

package/dist/scope/acceptance-evidence.d.ts

@@ -58,7 +58,7 @@ export interface AcceptanceEvidenceGateResult {
     readonly message: string;
     readonly reports: readonly CriterionAcceptanceReport[];
     /** How the #3357 walk obtained AC (#3387). */
-    readonly servedFrom?: "bank" | "cache" | "executed";
+    readonly servedFrom?: "bank" | "cache" | "executed" | "refused";
     /** Which acceptance check decided the walk (#3497). Undefined when no walk ran. */
     readonly predicate?: AcceptancePredicate;
 }

package/dist/scope/transition.js

@@ -5,6 +5,7 @@ import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemet
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { applyClauseDerivationToPlan, maybeEmitAcceptanceStampFromChange, } from "../intake/clause-derivation.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
+import { stampExistingEnvelopes } from "../lifecycle/brief-envelope.js";
 import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
 import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
 import { evaluateAcceptanceActivateGate } from "./acceptance-activate-gate.js";
@@ -45,18 +46,6 @@ function advanceNonTerminalOwnItems(items, targetStatus) {
         advanceNonTerminalOwnItems(obj.items, targetStatus);
     }
 }
-/**
- * Refresh the document envelope `updated` stamp to match `plan.updated`.
- * Stamps whichever of xBRIEFInfo (v0.8) / vBRIEFInfo (v0.6) is present — never creates one (#2862 / #2346).
- */
-function stampEnvelopeUpdated(data, nowIso) {
-    for (const key of ["xBRIEFInfo", "vBRIEFInfo"]) {
-        const env = data[key];
-        if (typeof env === "object" && env !== null && !Array.isArray(env)) {
-            env.updated = nowIso;
-        }
-    }
-}
 export function runTransition(action, filePath, now = new Date(), options = {}) {
     if (!(action in TRANSITIONS)) {
         const valid = Object.keys(TRANSITIONS).sort().join(", ");
@@ -255,7 +244,8 @@ export function runTransition(action, filePath, now = new Date(), options = {})
     planObj.status = targetStatus;
     planObj.updated = nowIso;
     // Keep the envelope clock aligned with plan.updated on every mutating transition (#2862).
-    stampEnvelopeUpdated(data, nowIso);
+    // Stamps whichever envelope is present, never creates one (#3933 / #2346).
+    stampExistingEnvelopes(data, nowIso);
     // Reconcile the completing brief's own plan.items (mirrors #1527 / #2566 registry sync) (#2862).
     // On complete, items only reach here when #3240 evidence/disposition gate passed.
     if (OWN_ITEMS_RECONCILE_ACTIONS.has(act)) {
@@ -412,7 +402,7 @@ function restampCompletedBrief(args) {
     }
     planObj.status = "completed";
     planObj.updated = nowIso;
-    stampEnvelopeUpdated(data, nowIso);
+    stampExistingEnvelopes(data, nowIso);
     stampCompletionMetadata(planObj, projectRoot, nowIso, {
         completedSessionId: resolveCompletionSessionId(projectRoot),
     });

package/dist/session/ac-pass-banking.d.ts

@@ -12,8 +12,8 @@
  */
 import { type AcPassBankingConfig } from "../policy/ac-pass-banking.js";
 import type { HardEffortBudget, VerificationDepthPolicy } from "./effort-budget.js";
-/** Durable bank ledger directory (gitignored under `.deft/`). */
-export declare const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+/** Durable bank ledger directory (under already-ignored `.deft/cache/`). */
+export declare const AC_PASS_BANK_DIR = ".deft/cache/ac-pass-banks";
 export declare const AC_PASS_BANK_SCHEMA_VERSION: 1;
 /** Env path for optional JSONL run summary (#3282). Unset = silent. */
 export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";

package/dist/session/ac-pass-banking.js

@@ -18,8 +18,8 @@ import { DEFAULT_SURPLUS_THRESHOLD, resolveAcPassBanking, } from "../policy/ac-p
 import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { detectHardEffortBudget, formatDeepeningSkippedNote, recommendVerificationDepth, } from "./effort-budget.js";
 import { gitHead } from "./git.js";
-/** Durable bank ledger directory (gitignored under `.deft/`). */
-export const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+/** Durable bank ledger directory (under already-ignored `.deft/cache/`). */
+export const AC_PASS_BANK_DIR = ".deft/cache/ac-pass-banks";
 export const AC_PASS_BANK_SCHEMA_VERSION = 1;
 /** Env path for optional JSONL run summary (#3282). Unset = silent. */
 export const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";

package/dist/session/host-session-owner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where a host publishes the session id Directive uses as the occupancy owner
+ * (#3611 / #3873).
+ *
+ * This is payload/environment classification, not authentication: cooperative
+ * owner ids are locally forgeable by another same-user process. It lives here,
+ * outside the hook classifier, because two processes must agree on the answer.
+ * The hook resolves it from its own environment; the CLI resolves it from the
+ * shell the same host spawned. A claim made under a different id than the write
+ * gate later presents is the #3873 defect -- the session denied by its own lease.
+ */
+export declare const HOST_IDENTITY_PROVIDERS: readonly ["codex", "claude", "cursor", "grok"];
+export type HookHostIdentityProvider = (typeof HOST_IDENTITY_PROVIDERS)[number];
+export declare const MAX_HOOK_HOST_IDENTITY_UTF8_BYTES = 512;
+/**
+ * Where a provider publishes its owner id.
+ *
+ * `payload` providers carry a verified field on every hook invocation.
+ * `host-env` providers publish a stable id in the environment of the processes
+ * the host spawns. That environment is host-set: the hook is a sibling of the
+ * agent's shell rather than a descendant, so a shell export cannot reach it.
+ */
+export type HookHostIdentitySource = {
+    readonly kind: "payload";
+    readonly field: string;
+} | {
+    readonly kind: "host-env";
+    readonly variable: string;
+};
+/** The identity source for a host, or null when the host has no contract. */
+export declare function hookHostIdentitySource(host: string): HookHostIdentitySource | null;
+/** Bound a raw host id by UTF-8 bytes, control characters and surrogate pairing. */
+export declare function isUsableHostSessionId(raw: string): boolean;
+export declare function canonicalHostSessionId(provider: HookHostIdentityProvider, rawSessionId: string): string;
+export type HostEnvIdentityStatus = "ok" | "missing" | "invalid";
+export type HostEnvIdentityResolution = {
+    readonly status: "ok";
+    readonly rawSessionId: string;
+} | {
+    readonly status: "missing" | "invalid";
+    readonly rawSessionId: null;
+};
+/** Read one `host-env` provider's variable out of a process environment. */
+export declare function readHostEnvIdentity(environ: NodeJS.ProcessEnv, variable: string): HostEnvIdentityResolution;
+/**
+ * The canonical owner the running host published to this process, or null.
+ *
+ * Used by the CLI claim path so `session:start` binds the lease to the same id
+ * the write hook will present. Two live host variables are ambiguous and
+ * resolve to null: picking one would bind a claim to a guess.
+ */
+export declare function ambientHostSessionOwner(environ?: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=host-session-owner.d.ts.map

package/dist/session/host-session-owner.js

@@ -0,0 +1,89 @@
+/**
+ * Where a host publishes the session id Directive uses as the occupancy owner
+ * (#3611 / #3873).
+ *
+ * This is payload/environment classification, not authentication: cooperative
+ * owner ids are locally forgeable by another same-user process. It lives here,
+ * outside the hook classifier, because two processes must agree on the answer.
+ * The hook resolves it from its own environment; the CLI resolves it from the
+ * shell the same host spawned. A claim made under a different id than the write
+ * gate later presents is the #3873 defect -- the session denied by its own lease.
+ */
+export const HOST_IDENTITY_PROVIDERS = ["codex", "claude", "cursor", "grok"];
+export const MAX_HOOK_HOST_IDENTITY_UTF8_BYTES = 512;
+const HOST_IDENTITY_SOURCES = {
+    codex: { kind: "payload", field: "session_id" },
+    claude: { kind: "payload", field: "session_id" },
+    cursor: { kind: "payload", field: "conversation_id" },
+    grok: { kind: "host-env", variable: "GROK_SESSION_ID" },
+};
+/** The identity source for a host, or null when the host has no contract. */
+export function hookHostIdentitySource(host) {
+    return (HOST_IDENTITY_SOURCES[host] ?? null);
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit <= 0x1f || (unit >= 0x7f && unit <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function hasUnpairedUtf16Surrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+            continue;
+        }
+        if (unit >= 0xdc00 && unit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+/** Bound a raw host id by UTF-8 bytes, control characters and surrogate pairing. */
+export function isUsableHostSessionId(raw) {
+    return (raw.length > 0 &&
+        raw === raw.trim() &&
+        !hasControlCharacter(raw) &&
+        !hasUnpairedUtf16Surrogate(raw) &&
+        Buffer.byteLength(raw, "utf8") <= MAX_HOOK_HOST_IDENTITY_UTF8_BYTES);
+}
+export function canonicalHostSessionId(provider, rawSessionId) {
+    const encoded = Buffer.from(rawSessionId, "utf8").toString("base64url");
+    return `host:${provider}:v1:${encoded}`;
+}
+/** Read one `host-env` provider's variable out of a process environment. */
+export function readHostEnvIdentity(environ, variable) {
+    const raw = environ[variable];
+    // An unset variable and an empty one are one state to a host: `set X=` on
+    // Windows deletes the entry, so absence must not read as a malformed value.
+    if (raw === undefined || raw.length === 0)
+        return { status: "missing", rawSessionId: null };
+    return isUsableHostSessionId(raw)
+        ? { status: "ok", rawSessionId: raw }
+        : { status: "invalid", rawSessionId: null };
+}
+/**
+ * The canonical owner the running host published to this process, or null.
+ *
+ * Used by the CLI claim path so `session:start` binds the lease to the same id
+ * the write hook will present. Two live host variables are ambiguous and
+ * resolve to null: picking one would bind a claim to a guess.
+ */
+export function ambientHostSessionOwner(environ = process.env) {
+    const resolved = [];
+    for (const provider of HOST_IDENTITY_PROVIDERS) {
+        const source = HOST_IDENTITY_SOURCES[provider];
+        if (source.kind !== "host-env")
+            continue;
+        const value = readHostEnvIdentity(environ, source.variable);
+        if (value.status === "ok")
+            resolved.push(canonicalHostSessionId(provider, value.rawSessionId));
+    }
+    return resolved.length === 1 ? resolved[0] : null;
+}
+//# sourceMappingURL=host-session-owner.js.map

package/dist/session/index.d.ts

@@ -6,6 +6,7 @@ export * from "./compact-ritual.js";
 export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
+export * from "./host-session-owner.js";
 export * from "./json.js";
 export * from "./occupancy.js";
 export * from "./openclaw-soft-rebind-deposit.js";

package/dist/session/index.js

@@ -6,6 +6,7 @@ export * from "./compact-ritual.js";
 export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
+export * from "./host-session-owner.js";
 export * from "./json.js";
 export * from "./occupancy.js";
 export * from "./openclaw-soft-rebind-deposit.js";

package/dist/session/occupancy.d.ts

@@ -218,7 +218,18 @@ export declare function formatOccupancyStaleWarning(record: OccupancyRecord, now
  * lease is gone rather than merely quiet, so the answer is to re-claim.
  */
 export declare function formatOccupancyAgeCapRemediation(record: OccupancyRecord, now?: Date, maxLeaseMs?: number): string;
-export declare function formatOccupancyRemediation(record: OccupancyRecord, now?: Date): string;
+/**
+ * Tell a refused caller who holds the lease and what it can actually run.
+ *
+ * `presented` is the id the refused caller offered (#3873). Without it the
+ * message can only print `<your-session-id>` placeholders, which is fine for a
+ * CLI caller that passed its own `--session-id` and useless to a hook process,
+ * which does not know what identity it presented. Passing it also keeps the
+ * message honest when there is none: a grant cannot name an empty child --
+ * `occupancy:grant --child-session-id=` is refused at parse and at membership --
+ * so that remediation is not printed to a caller who could never run it.
+ */
+export declare function formatOccupancyRemediation(record: OccupancyRecord, now?: Date, presented?: string): string;
 /**
  * Refuse an administrative verb to a granted child (#3755). Named apart from
  * the stranger refusal because the answer differs: this caller is admitted, and
@@ -226,6 +237,15 @@ export declare function formatOccupancyRemediation(record: OccupancyRecord, now?
  * derives from. A grant admits writes; the lease has one owner.
  */
 export declare function formatOccupancyMemberAdministrationRefusal(record: OccupancyRecord, grant: OccupancyGrant, verb: string): string;
+/**
+ * The owner a claim is made under: an explicit id, then `DEFT_SESSION_ID`, then
+ * the id the running host published, then a mint.
+ *
+ * The host step is what makes an identified host's claim reachable (#3873).
+ * Minting instead binds the lease to an id no later hook process can present,
+ * so the session that claimed the worktree is refused by its own lease. The
+ * mint stays as the last resort for hosts that publish nothing.
+ */
 export declare function resolveOccupancySessionId(input?: ApplyOccupancyInput): string;
 export declare function readOccupancy(projectRoot: string): OccupancyRecord | null;
 export declare function liveOccupant(projectRoot: string, now?: Date, ttlMs?: number, maxLeaseMs?: number): OccupancyRecord | null;