@deftai/directive-core 0.108.0 → 0.109.1

package/dist/session/child-occupancy.js

@@ -0,0 +1,209 @@
+/**
+ * Dispatch-recorded child occupancy leases (#3999).
+ *
+ * A parent records the child's occupancy owner and the exact worktree root at
+ * dispatch in `.deft/child-occupancy/` — lease-gated, not `.deft-scratch/**`.
+ * The orchestration terminal transition already carries agent_id / parent_id /
+ * phase; this store is the missing occupancy-owner datum. Release reuses
+ * `releaseOccupancy` under the occupancy lock and only fires when the recorded
+ * child is still the current owner of the recorded tree.
+ *
+ * Per identity-source kind: `host-env` children are strangers and strand —
+ * that is the defect. `payload` parents share one id with their children, so
+ * the same transition is a no-op; auto-release would drop a live parent lease
+ * mid-flight. Swarm close-out of the launcher's occupancy_session_id is not
+ * the precedent and is not copied here.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedRemove, containedWrite } from "../fs/contained-write.js";
+import { hookHostIdentitySource } from "./host-session-owner.js";
+import { stableJson } from "./json.js";
+import { readOccupancy, releaseOccupancy } from "./occupancy.js";
+export const CHILD_OCCUPANCY_SCHEMA_VERSION = 1;
+export const CHILD_OCCUPANCY_DIR = [".deft", "child-occupancy"];
+export const CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS = ["host-env", "payload"];
+function isIdentitySourceKind(value) {
+    return CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS.includes(value);
+}
+/** Filename-safe agent id; the payload keeps the original. */
+export function childOccupancyFileSegment(agentId) {
+    let cleaned = "";
+    for (const ch of agentId.trim()) {
+        if ((ch >= "A" && ch <= "Z") ||
+            (ch >= "a" && ch <= "z") ||
+            (ch >= "0" && ch <= "9") ||
+            ch === "." ||
+            ch === "_" ||
+            ch === "-") {
+            cleaned += ch;
+        }
+        else {
+            cleaned += "-";
+        }
+    }
+    let start = 0;
+    let end = cleaned.length;
+    while (start < end && (cleaned[start] === "-" || cleaned[start] === "."))
+        start += 1;
+    while (end > start && (cleaned[end - 1] === "-" || cleaned[end - 1] === "."))
+        end -= 1;
+    cleaned = cleaned.slice(start, end);
+    return cleaned.length > 0 ? cleaned : "agent";
+}
+export function childOccupancyRelpath(agentId) {
+    return [...CHILD_OCCUPANCY_DIR, `${childOccupancyFileSegment(agentId)}.json`];
+}
+export function childOccupancyPath(storeRoot, agentId) {
+    return join(resolve(storeRoot), ...childOccupancyRelpath(agentId));
+}
+export function childOccupancyIdentitySourceKind(host) {
+    const source = hookHostIdentitySource(host);
+    if (source === null)
+        return null;
+    return source.kind;
+}
+function parseChildOccupancyRecord(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const obj = payload;
+    const agentId = typeof obj.agent_id === "string" ? obj.agent_id.trim() : "";
+    const parentId = typeof obj.parent_id === "string" ? obj.parent_id.trim() : "";
+    const occupancyOwner = typeof obj.occupancy_owner === "string" ? obj.occupancy_owner.trim() : "";
+    const worktreePath = typeof obj.worktree_path === "string" ? obj.worktree_path.trim() : "";
+    const kindRaw = typeof obj.identity_source_kind === "string" ? obj.identity_source_kind.trim() : "";
+    if (agentId.length === 0 ||
+        parentId.length === 0 ||
+        occupancyOwner.length === 0 ||
+        worktreePath.length === 0 ||
+        !isIdentitySourceKind(kindRaw)) {
+        return null;
+    }
+    return {
+        schemaVersion: typeof obj.schemaVersion === "number" ? obj.schemaVersion : CHILD_OCCUPANCY_SCHEMA_VERSION,
+        agentId,
+        parentId,
+        occupancyOwner,
+        worktreePath,
+        identitySourceKind: kindRaw,
+    };
+}
+export function readChildOccupancyLease(storeRoot, agentId) {
+    const path = childOccupancyPath(storeRoot, agentId);
+    try {
+        if (!existsSync(path))
+            return null;
+        return parseChildOccupancyRecord(JSON.parse(readFileSync(path, { encoding: "utf8" })));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parent-only write at dispatch. Workers cannot author this store: `.deft/` is
+ * not assist-scratch, so a mutation write is occupancy-gated and an assist
+ * writer does not get the scratch carve-out.
+ */
+export function recordChildOccupancyLease(storeRoot, input) {
+    const agentId = input.agentId.trim();
+    const parentId = input.parentId.trim();
+    const occupancyOwner = input.occupancyOwner.trim();
+    const worktreePath = resolve(input.worktreePath.trim());
+    if (agentId.length === 0)
+        throw new Error("recordChildOccupancyLease needs agentId");
+    if (parentId.length === 0)
+        throw new Error("recordChildOccupancyLease needs parentId");
+    if (occupancyOwner.length === 0) {
+        throw new Error("recordChildOccupancyLease needs occupancyOwner");
+    }
+    if (input.worktreePath.trim().length === 0) {
+        throw new Error("recordChildOccupancyLease needs worktreePath");
+    }
+    const record = {
+        schemaVersion: CHILD_OCCUPANCY_SCHEMA_VERSION,
+        agentId,
+        parentId,
+        occupancyOwner,
+        worktreePath,
+        identitySourceKind: input.identitySourceKind,
+    };
+    const root = resolve(storeRoot);
+    const relpath = childOccupancyRelpath(agentId);
+    mkdirSync(join(root, ...CHILD_OCCUPANCY_DIR), { recursive: true });
+    containedWrite({
+        root,
+        target: join(...relpath),
+        data: `${stableJson({
+            schemaVersion: record.schemaVersion,
+            agent_id: record.agentId,
+            parent_id: record.parentId,
+            occupancy_owner: record.occupancyOwner,
+            worktree_path: record.worktreePath,
+            identity_source_kind: record.identitySourceKind,
+        }, 2)}\n`,
+        mode: "replace",
+    });
+    return record;
+}
+function removeChildOccupancyLease(storeRoot, agentId) {
+    const root = resolve(storeRoot);
+    const relpath = childOccupancyRelpath(agentId);
+    const abs = join(root, ...relpath);
+    if (!existsSync(abs))
+        return;
+    containedRemove({ root, target: join(...relpath) });
+}
+/**
+ * Compare-and-release under the occupancy lock. Caller identity is the id the
+ * parent recorded at dispatch — not the occupant currently named in the lease
+ * file, and not a field on a worker-authored heartbeat.
+ */
+export function releaseChildOccupancyOnTerminal(storeRoot, input) {
+    const agentId = input.agentId.trim();
+    if (agentId.length === 0) {
+        return { reason: "missing-record", record: null, occupancy: null };
+    }
+    const record = readChildOccupancyLease(storeRoot, agentId);
+    if (record === null) {
+        return { reason: "missing-record", record: null, occupancy: null };
+    }
+    if (record.identitySourceKind === "payload") {
+        return { reason: "payload-skip", record, occupancy: null };
+    }
+    const tree = resolve(record.worktreePath);
+    const now = input.now ?? new Date();
+    const live = readOccupancy(tree);
+    if (live === null) {
+        removeChildOccupancyLease(storeRoot, agentId);
+        return { reason: "already-free", record, occupancy: null };
+    }
+    if (live.sessionId !== record.occupancyOwner) {
+        return { reason: "owner-changed", record, occupancy: null };
+    }
+    const occupancy = releaseOccupancy(tree, {
+        sessionId: record.occupancyOwner,
+        now,
+        env: {},
+        lockDeps: input.lockDeps,
+    });
+    if (occupancy.action === "released") {
+        removeChildOccupancyLease(storeRoot, agentId);
+        if (resolve(storeRoot) !== tree)
+            removeChildOccupancyLease(tree, agentId);
+        return { reason: "released", record, occupancy };
+    }
+    return { reason: "denied", record, occupancy };
+}
+/**
+ * Worktree guesses for a heartbeat file. Canonical layout is
+ * `<worktree>/.deft-scratch/subagent-status/<agent>.json`; cwd is the fallback
+ * when the scratch dir was passed as a custom path.
+ */
+export function worktreeCandidatesForHeartbeat(heartbeatPath, cwd) {
+    const fromHeartbeat = resolve(heartbeatPath, "..", "..", "..");
+    const fromCwd = resolve(cwd);
+    if (fromHeartbeat === fromCwd)
+        return [fromHeartbeat];
+    return [fromHeartbeat, fromCwd];
+}
+//# sourceMappingURL=child-occupancy.js.map

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

@@ -0,0 +1,93 @@
+/**
+ * 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;
+};
+/**
+ * Every variable a `host-env` provider publishes.
+ *
+ * Exported because the ambient step is now read by the CLI occupancy surfaces
+ * as well as the hook, so callers that must control the whole ambient identity
+ * surface — a hermetic test process, a dispatcher scrubbing a child's
+ * environment — need the list rather than the one variable its author knew
+ * about (#3954).
+ */
+export declare const HOST_ENV_IDENTITY_VARIABLES: readonly 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;
+/**
+ * The canonical owner form, derived from the provider list so every surface
+ * that checks it moves when a provider is added: the lifecycle-rewrite bridge
+ * and grant-time child validation both read this one pattern (#3873 / #3954).
+ * Provider ids are lowercase ASCII words, so the alternation needs no escaping.
+ */
+export declare const CANONICAL_OWNER_PATTERN: RegExp;
+/**
+ * True when a value claims the canonical owner shape, well-formed or not.
+ *
+ * The `host:` prefix is reserved for host-published identity, so a value under
+ * it that is not canonical is a malformed owner rather than an opaque id some
+ * session could present (#3954).
+ */
+export declare function claimsHostSessionIdShape(value: string): boolean;
+export interface HostSessionIdParts {
+    readonly provider: HookHostIdentityProvider;
+    readonly rawSessionId: string;
+}
+/**
+ * Split a canonical owner back into the provider and the raw id the host
+ * published, or null when the value is not canonical.
+ *
+ * The round-trip check is the point: `host:grok:v1:Z3Jvay1zZXNzaW9uLWF` decodes
+ * to the same raw id as `...LWE` does, so without it one session would have two
+ * canonical strings and a grant could name the one it never presents (#3954).
+ * The raw id is held to the same bound the identity surface applies, so a
+ * payload the host could not have published is not accepted here either.
+ */
+export declare function parseCanonicalHostSessionId(value: string): HostSessionIdParts | null;
+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,148 @@
+/**
+ * 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 `host-env` half of the table above, resolved once.
+ *
+ * `ambientHostSessionOwner` reads it to build the owner list, and
+ * `HOST_ENV_IDENTITY_VARIABLES` projects the variable names out of the same
+ * entries, so the production scan and the surface a caller scrubs cannot name
+ * different providers (#3954).
+ */
+const HOST_ENV_IDENTITY_ENTRIES = HOST_IDENTITY_PROVIDERS.flatMap((provider) => {
+    const source = HOST_IDENTITY_SOURCES[provider];
+    return source.kind === "host-env" ? [{ provider, variable: source.variable }] : [];
+});
+/**
+ * Every variable a `host-env` provider publishes.
+ *
+ * Exported because the ambient step is now read by the CLI occupancy surfaces
+ * as well as the hook, so callers that must control the whole ambient identity
+ * surface — a hermetic test process, a dispatcher scrubbing a child's
+ * environment — need the list rather than the one variable its author knew
+ * about (#3954).
+ */
+export const HOST_ENV_IDENTITY_VARIABLES = HOST_ENV_IDENTITY_ENTRIES.map((entry) => entry.variable);
+/** 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}`;
+}
+/**
+ * The canonical owner form, derived from the provider list so every surface
+ * that checks it moves when a provider is added: the lifecycle-rewrite bridge
+ * and grant-time child validation both read this one pattern (#3873 / #3954).
+ * Provider ids are lowercase ASCII words, so the alternation needs no escaping.
+ */
+export const CANONICAL_OWNER_PATTERN = new RegExp(`^host:(?:${HOST_IDENTITY_PROVIDERS.join("|")}):v1:[A-Za-z0-9_-]+$`);
+/**
+ * True when a value claims the canonical owner shape, well-formed or not.
+ *
+ * The `host:` prefix is reserved for host-published identity, so a value under
+ * it that is not canonical is a malformed owner rather than an opaque id some
+ * session could present (#3954).
+ */
+export function claimsHostSessionIdShape(value) {
+    return value.startsWith("host:");
+}
+/**
+ * Split a canonical owner back into the provider and the raw id the host
+ * published, or null when the value is not canonical.
+ *
+ * The round-trip check is the point: `host:grok:v1:Z3Jvay1zZXNzaW9uLWF` decodes
+ * to the same raw id as `...LWE` does, so without it one session would have two
+ * canonical strings and a grant could name the one it never presents (#3954).
+ * The raw id is held to the same bound the identity surface applies, so a
+ * payload the host could not have published is not accepted here either.
+ */
+export function parseCanonicalHostSessionId(value) {
+    if (!CANONICAL_OWNER_PATTERN.test(value))
+        return null;
+    const segments = value.split(":");
+    const provider = segments[1];
+    const encoded = segments[3] ?? "";
+    const rawSessionId = Buffer.from(encoded, "base64url").toString("utf8");
+    if (!isUsableHostSessionId(rawSessionId))
+        return null;
+    if (canonicalHostSessionId(provider, rawSessionId) !== value)
+        return null;
+    return { provider, rawSessionId };
+}
+/** 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, variable } of HOST_ENV_IDENTITY_ENTRIES) {
+        const value = readHostEnvIdentity(environ, 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

@@ -2,10 +2,12 @@ export * from "./ac-pass-banking.js";
 export * from "./ac-pass-reuse.js";
 export * from "./active-cli.js";
 export * from "./ceremony-dial-evidence.js";
+export * from "./child-occupancy.js";
 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

@@ -2,10 +2,12 @@ export * from "./ac-pass-banking.js";
 export * from "./ac-pass-reuse.js";
 export * from "./active-cli.js";
 export * from "./ceremony-dial-evidence.js";
+export * from "./child-occupancy.js";
 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

@@ -19,6 +19,25 @@
  * composite hook write gate measures the tree's verified ritual owner against
  * the occupant that issued the grant, not against the writer.
  *
+ * Parent and child, answered per identity-source kind (#3954, and it does not
+ * have one answer). On a `host-env` host the parent and its dispatched children
+ * are different actors, because the host publishes a different id into each
+ * agent session. The answer there is identity, not automatic membership: each
+ * side resolves its own owner through the shared lookup chain below and claims
+ * its own worktree, which is where the dispatch envelope already puts it.
+ * Membership stays explicit and owner-issued for the deliberate same-tree case,
+ * and it stays affordable only that way -- 32 grants at a four-hour TTL against
+ * a twenty-minute lease means granting on every dispatch exhausts a busy
+ * parent's lease inside a day. The revocation trigger is therefore the owner's
+ * own `occupancy:grant --revoke`, or expiry; releasing a child's lease on its
+ * terminal event is dispatcher lifecycle in `child-occupancy.ts` (#3999).
+ * On a `payload` host parent and subagents share one id, so there is no foreign
+ * child lease to admit and nothing to grant -- and the live consequence is the
+ * inverse one: `owns` is true for both, so a parent's `occupancy:release`
+ * removes a working child's lease mid-flight with no denial. That is a property
+ * of shared host identity, not of this module; a bearer boundary cannot
+ * distinguish two processes presenting one string.
+ *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.
  * - Guarantees: mutual exclusion under crash-free operation; detect-and-abort
@@ -218,7 +237,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,11 +256,78 @@ 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;
+/** Which step of the shared lookup chain produced the actor (#3954). */
+export type PresentedIdentitySource = "explicit" | "environment" | "host" | "none";
+export interface PresentedIdentity {
+    /** The id this surface acts under; empty when nothing was presented. */
+    readonly sessionId: string;
+    readonly source: PresentedIdentitySource;
+    /**
+     * The owner the running host published, when it names a different session
+     * than `sessionId` does; otherwise null. This is the claimer-versus-presenter
+     * split itself: the id a session claims under and the id its hook process
+     * presents are two different sessions (#3954).
+     */
+    readonly disagreeingHostOwner: string | null;
+}
+/**
+ * The one lookup order every occupancy surface shares (#3954): an explicit
+ * `--session-id`, then `DEFT_SESSION_ID`, then the owner the running host
+ * published.
+ *
+ * The terminal is the caller's, not this function's. Claim mints, because
+ * claiming establishes an identity where none exists. Release, heartbeat and
+ * grant/revoke are proving one, so they take the empty string and keep the
+ * diagnosis written for it -- a shared mint would replace "you presented
+ * nothing" with a plausible id no later hook will ever present, on every host
+ * that publishes no owner of its own.
+ *
+ * Disagreement is reported, not resolved. The order stands, so an explicit id
+ * beats the environment and the environment beats the host; what changes is
+ * that a refused caller is told the host names someone else, which is the state
+ * a stale inherited `DEFT_SESSION_ID` produces and the one an operator cannot
+ * otherwise see.
+ */
+export declare function resolvePresentedIdentity(input?: {
+    readonly sessionId?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}): PresentedIdentity;
+/**
+ * Name a claimer-versus-presenter split on a refusal, or return "" (#3954).
+ *
+ * Appended only to denials: while the caller is admitted the split costs it
+ * nothing, and on a refusal it is the one fact that explains why an id the
+ * operator believes is theirs is being treated as a stranger's.
+ */
+export declare function formatPresentedIdentityDisagreement(identity: PresentedIdentity): string;
+/**
+ * The owner a claim is made under: the shared lookup chain, 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, and it is the
+ * one terminal the prove-surfaces deliberately do not share (#3954).
+ */
 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;
 export declare function applyWorktreeOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
 export declare function stealOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
+/**
+ * Release the caller's own lease.
+ *
+ * Owner-only, deliberately (#3954 item 4, answering the open question the
+ * design-critique arc left for the builder). Letting an unidentified caller
+ * release the occupant the lease file itself records would make possession of
+ * that file path into authority to delete a live lease, which is exactly what
+ * the `!expired && !owns` refusal exists to prevent -- and the cooperative
+ * bearer model (#3755) has no second check behind it. The unreachable printed
+ * recovery is fixed by the shared lookup chain instead: on a host that
+ * publishes an owner, the occupant now resolves itself and a bare
+ * `occupancy:release` is the occupant, so the message the deny prints is one
+ * the party it addresses can actually run.
+ */
 export declare function releaseOccupancy(projectRoot: string, input?: {
     readonly sessionId?: string;
     readonly env?: NodeJS.ProcessEnv;
@@ -313,7 +410,15 @@ export declare function evaluateOccupancyWriteGate(projectRoot: string, input?:
  * Never claims and never mints an owner — an unheld or foreign lease is denied.
  */
 export declare function heartbeatOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
-/** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
+/**
+ * Close-out identity comes from the launch manifest, `DEFT_SESSION_ID`, or the
+ * owner the running host published — never occupancy.json (#3954).
+ *
+ * Reading the lease for identity would be the anonymous recorded-occupant
+ * release refused in `releaseOccupancy`; the host step is the same shared
+ * lookup chain every other occupancy surface uses, so a cohort launched on a
+ * host that publishes an owner can close out without an explicit id.
+ */
 export declare function releaseSwarmOccupancy(projectRoot: string, input?: {
     readonly sessionId?: string;
     readonly env?: NodeJS.ProcessEnv;