@deftai/directive-core 0.108.0 → 0.109.1

package/dist/scm/call.js

@@ -1,27 +1,35 @@
 import { spawnSync } from "node:child_process";
 import { resolveCaptureFailureStderr, 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 { SUPPORTED_CALL_SOURCES } from "./constants.js";
 import { pyRepr } from "./py-format.js";
+import { formatScmSpawnDiagnostic, isAvailabilitySpawnFailure } from "./spawn-status.js";
 /**
  * Source-aware SCM invocation -- partial down-payment on #445 / #935 Workstream 6.
  * Mirrors `scripts/scm.py::call`.
  *
- * Binary absence still throws ScmStubError via resolveBinary with the #2275
- * diagnostic. Full auth readiness is enforced at SCM CLI entry points
+ * Binary absence still throws ScmStubError via resolveBinaryForRole with the
+ * #2275 diagnostic. Full auth readiness is enforced at SCM CLI entry points
  * (`scm/main`, issue-ingest, reconcile-issues) via requireScmReady — not on
  * every call() — so unit tests that inject binary/seams stay hermetic.
+ *
+ * Call-shape selection (#3737): ghx only for single-path GET. An explicit
+ * `binary` override skips selection and spawn-failure fallback.
  */
 export function call(source, verb, args = null, options = {}) {
     if (!SUPPORTED_CALL_SOURCES.includes(source)) {
         throw new Error(`source=${pyRepr(source)} not yet supported; ` +
             "see #445 / #935 Workstream 6 for the abstraction.");
     }
-    const resolved = options.binary ?? resolveBinary(options.whichFn);
-    const argv = [resolved, verb, ...(args ?? [])];
+    const whichFn = options.whichFn ?? defaultWhich;
+    const role = classifyScmArgv(verb, args ?? []);
+    const explicitBinary = options.binary;
+    let resolved = explicitBinary ?? resolveBinaryForRole(role, whichFn);
+    const extra = args ?? [];
     const captureOutput = options.captureOutput ?? true;
     const timeoutMs = options.timeout !== undefined ? Math.round(options.timeout * 1000) : undefined;
-    const result = spawnSync(resolved, [verb, ...(args ?? [])], {
+    const spawnOnce = (bin) => spawnSync(bin, [verb, ...extra], {
         cwd: options.cwd,
         env: options.env ?? process.env,
         input: options.input,
@@ -30,14 +38,36 @@ export function call(source, verb, args = null, options = {}) {
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         stdio: captureOutput ? ["pipe", "pipe", "pipe"] : "inherit",
     });
-    // A spawn-level failure (ENOBUFS past maxBuffer, timeout kill) yields a null
-    // status and empty stderr; surface error.message so callers never report a
-    // bare exit 1 with no reason (#1867 / #3903).
-    const stderr = resolveCaptureFailureStderr({
-        captured: typeof result.stderr === "string" ? result.stderr : "",
+    let result = spawnOnce(resolved);
+    if (explicitBinary === undefined &&
+        role === "cached-get" &&
+        resolved === "ghx" &&
+        isAvailabilitySpawnFailure({
+            status: result.status,
+            error: result.error,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: typeof result.stderr === "string" ? result.stderr : "",
+        }) &&
+        whichFn("gh") !== null) {
+        resolved = "gh";
+        result = spawnOnce(resolved);
+    }
+    const argv = [resolved, verb, ...extra];
+    const captured = typeof result.stderr === "string" ? result.stderr : "";
+    let stderr = resolveCaptureFailureStderr({
+        captured,
         status: result.status,
         message: result.error?.message,
     });
+    if (isAvailabilitySpawnFailure({
+        status: result.status,
+        error: result.error,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: captured,
+    }) &&
+        stderr.trim().length === 0) {
+        stderr = formatScmSpawnDiagnostic(resolved, result.status, stderr, result.error);
+    }
     if (options.check && result.status !== 0) {
         const error = new Error(stderr || `Process exited with code ${result.status}`);
         throw error;

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/child-occupancy.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 type { LockDeps } from "../slice/lock.js";
+import { type OccupancyDecision } from "./occupancy.js";
+export declare const CHILD_OCCUPANCY_SCHEMA_VERSION = 1;
+export declare const CHILD_OCCUPANCY_DIR: readonly [".deft", "child-occupancy"];
+export declare const CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS: readonly ["host-env", "payload"];
+export type ChildOccupancyIdentitySourceKind = (typeof CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS)[number];
+export interface ChildOccupancyRecord {
+    readonly schemaVersion: number;
+    readonly agentId: string;
+    readonly parentId: string;
+    readonly occupancyOwner: string;
+    readonly worktreePath: string;
+    readonly identitySourceKind: ChildOccupancyIdentitySourceKind;
+}
+export interface ChildOccupancyDispatchInput {
+    readonly agentId: string;
+    readonly parentId: string;
+    readonly occupancyOwner: string;
+    readonly worktreePath: string;
+    readonly identitySourceKind: ChildOccupancyIdentitySourceKind;
+}
+export type ChildOccupancyReleaseReason = "released" | "already-free" | "owner-changed" | "payload-skip" | "missing-record" | "denied";
+export interface ChildOccupancyReleaseResult {
+    readonly reason: ChildOccupancyReleaseReason;
+    readonly record: ChildOccupancyRecord | null;
+    readonly occupancy: OccupancyDecision | null;
+}
+/** Filename-safe agent id; the payload keeps the original. */
+export declare function childOccupancyFileSegment(agentId: string): string;
+export declare function childOccupancyRelpath(agentId: string): string[];
+export declare function childOccupancyPath(storeRoot: string, agentId: string): string;
+export declare function childOccupancyIdentitySourceKind(host: string): ChildOccupancyIdentitySourceKind | null;
+export declare function readChildOccupancyLease(storeRoot: string, agentId: string): ChildOccupancyRecord | 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 declare function recordChildOccupancyLease(storeRoot: string, input: ChildOccupancyDispatchInput): ChildOccupancyRecord;
+/**
+ * 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 declare function releaseChildOccupancyOnTerminal(storeRoot: string, input: {
+    readonly agentId: string;
+    readonly now?: Date;
+    readonly lockDeps?: LockDeps;
+}): ChildOccupancyReleaseResult;
+/**
+ * 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 declare function worktreeCandidatesForHeartbeat(heartbeatPath: string, cwd: string): readonly string[];
+//# sourceMappingURL=child-occupancy.d.ts.map