@deftai/directive-core 0.107.0 → 0.109.0

package/dist/design-critique/completed-arc-record.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Completed-arc record for design-critique ingest (#3806).
+ *
+ * Catalog chips are list-visible convenience, not clearance. Ingest waits on
+ * `design-critique: synthesis accepted, because ...` citing an accepted
+ * successor lean (and the verified-claims table when that comment exists).
+ *
+ * Citations are parsed once, by `scanCitations` (#3831). The accepted forms and
+ * the refused positions are published in `content/contracts/design-critique.md`
+ * `## Citation grammar`. Clearance is set membership against the latest
+ * successor lean, not position in the body, so citing the superseded lean --
+ * which `## Successor lean` requires -- cannot block.
+ */
+export type ThreadComment = {
+    readonly id: number;
+    readonly body: string;
+};
+export type CompletedArcBlockReason = "missing-record" | "lone-shape" | "cite-not-lean" | "missing-table-cite" | "ambiguous-table-cite";
+export type CompletedArcVerdict = {
+    readonly status: "not-in-arc";
+} | {
+    readonly status: "complete";
+    readonly synthesisCommentId: number;
+    readonly citedLeanId: number;
+    readonly citedTableId: number | null;
+} | {
+    readonly status: "blocked";
+    readonly reason: CompletedArcBlockReason;
+    readonly detail: string;
+};
+export declare class DesignCritiqueIngestBlockedError extends Error {
+    readonly issueNumber: number;
+    readonly reason: CompletedArcBlockReason;
+    constructor(issueNumber: number, reason: CompletedArcBlockReason, detail: string);
+}
+export declare function isSynthesisAcceptedShape(body: string): boolean;
+export declare function isSuccessorLeanBody(body: string): boolean;
+export declare function isVerifiedClaimsTableBody(body: string): boolean;
+/**
+ * Ids cited by one comment body, in document order. Thin projection of the
+ * shared parser -- the grammar itself lives in `citation-grammar.ts`.
+ */
+export declare function extractCitedCommentIds(body: string): number[];
+export declare function hasDesignCritiqueCatalogChip(labels: readonly string[]): boolean;
+export declare function isPanelDepositBody(body: string): boolean;
+export declare function isInFlightCritiqueThread(comments: readonly ThreadComment[]): boolean;
+/**
+ * Ingest clearance from thread structure. Labels and author identity are not
+ * predicates. A lone synthesis-accepted sentence shape is not the record.
+ * Clearance cites the latest successor lean; an older complete record does not
+ * clear a later recut. A panel-deposit is in-flight even before critic posts.
+ */
+export declare function evaluateCompletedArcRecord(input: {
+    readonly labels?: readonly string[];
+    readonly comments: readonly ThreadComment[];
+}): CompletedArcVerdict;
+export declare function assertCompletedArcAllowsIngest(input: {
+    readonly issueNumber: number;
+    readonly labels?: readonly string[];
+    readonly comments: readonly ThreadComment[];
+}): CompletedArcVerdict;
+//# sourceMappingURL=completed-arc-record.d.ts.map

package/dist/design-critique/completed-arc-record.js

@@ -0,0 +1,277 @@
+/**
+ * Completed-arc record for design-critique ingest (#3806).
+ *
+ * Catalog chips are list-visible convenience, not clearance. Ingest waits on
+ * `design-critique: synthesis accepted, because ...` citing an accepted
+ * successor lean (and the verified-claims table when that comment exists).
+ *
+ * Citations are parsed once, by `scanCitations` (#3831). The accepted forms and
+ * the refused positions are published in `content/contracts/design-critique.md`
+ * `## Citation grammar`. Clearance is set membership against the latest
+ * successor lean, not position in the body, so citing the superseded lean --
+ * which `## Successor lean` requires -- cannot block.
+ */
+import { ACCEPTED_CITATION_FORMS, scanCitations, } from "./citation-grammar.js";
+import { DESIGN_CRITIQUE_CATALOG_CHIPS } from "./exclusive-chip.js";
+const SYNTHESIS_SHAPE_RE = /(?:^|\n)\s*design-critique:\s*synthesis accepted,\s*because\b/i;
+const LEAN_HEADING_RE = /(?:^|\n)\s*\*{0,2}Lean:\*{0,2}/;
+const TABLE_HEADING_RE = /(?:^|\n)\s*##\s+Verified-claims table\b/;
+/** How many ids a block detail lists before it truncates. */
+const DETAIL_ID_LIMIT = 5;
+const CATALOG = new Set(DESIGN_CRITIQUE_CATALOG_CHIPS);
+export class DesignCritiqueIngestBlockedError extends Error {
+    issueNumber;
+    reason;
+    constructor(issueNumber, reason, detail) {
+        super(`issue:ingest refused #${issueNumber}: design-critique ${reason} (${detail}) -- nothing written.`);
+        this.name = "DesignCritiqueIngestBlockedError";
+        this.issueNumber = issueNumber;
+        this.reason = reason;
+    }
+}
+export function isSynthesisAcceptedShape(body) {
+    return SYNTHESIS_SHAPE_RE.test(body);
+}
+export function isSuccessorLeanBody(body) {
+    return LEAN_HEADING_RE.test(body);
+}
+export function isVerifiedClaimsTableBody(body) {
+    return TABLE_HEADING_RE.test(body);
+}
+/**
+ * Ids cited by one comment body, in document order. Thin projection of the
+ * shared parser -- the grammar itself lives in `citation-grammar.ts`.
+ */
+export function extractCitedCommentIds(body) {
+    const ids = [];
+    const seen = new Set();
+    for (const citation of scanCitations(body).citations) {
+        if (seen.has(citation.id))
+            continue;
+        seen.add(citation.id);
+        ids.push(citation.id);
+    }
+    return ids;
+}
+export function hasDesignCritiqueCatalogChip(labels) {
+    return labels.some((name) => CATALOG.has(name));
+}
+const CRITIC_ROLE_RE = /(?:^|\n)\s*role:\s*critic\b/i;
+const MECHANISM_SHAPED_FIELD_RE = /(?:^|\n)\s*mechanism-shaped:\s*true\b/i;
+const PANEL_DEPOSIT_RE = /(?:^|\n)\s*panel-deposit\b/i;
+const PARENT_ROLE_RE = /(?:^|\n)\s*role:\s*parent\b/i;
+const SIBLINGS_FIELD_RE = /(?:^|\n)\s*siblings:\s*\d+/i;
+const INPUT_CEILING_FIELD_RE = /(?:^|\n)\s*input-ceiling:\s*\d+/i;
+export function isPanelDepositBody(body) {
+    if (PANEL_DEPOSIT_RE.test(body))
+        return true;
+    return (PARENT_ROLE_RE.test(body) && SIBLINGS_FIELD_RE.test(body) && INPUT_CEILING_FIELD_RE.test(body));
+}
+export function isInFlightCritiqueThread(comments) {
+    return comments.some((comment) => isSuccessorLeanBody(comment.body) ||
+        CRITIC_ROLE_RE.test(comment.body) ||
+        MECHANISM_SHAPED_FIELD_RE.test(comment.body) ||
+        isPanelDepositBody(comment.body));
+}
+function byId(comments) {
+    const map = new Map();
+    for (const comment of comments) {
+        map.set(comment.id, comment);
+    }
+    return map;
+}
+function latestSuccessorLean(comments) {
+    let latest;
+    for (const comment of comments) {
+        if (!isSuccessorLeanBody(comment.body))
+            continue;
+        if (latest === undefined || comment.id > latest.id)
+            latest = comment;
+    }
+    return latest;
+}
+function renderIds(ids) {
+    const shown = ids.slice(0, DETAIL_ID_LIMIT).join(", ");
+    return ids.length > DETAIL_ID_LIMIT
+        ? `${shown}, and ${ids.length - DETAIL_ID_LIMIT} more`
+        : shown;
+}
+/**
+ * Report what was scanned and what was found. A guess at the cause sends the
+ * operator back to re-post the same body and reproduce the block (#3831).
+ */
+function loneShapeDetail(scan) {
+    const parts = [
+        "synthesis-accepted sentence shape is present but cites no accepted successor lean",
+    ];
+    if (scan.idShapedRuns.length === 0) {
+        parts.push("no 8-or-more digit id appears in the body");
+    }
+    else {
+        parts.push(`${scan.idShapedRuns.length} 8-or-more digit id(s) appear in the body: ` +
+            renderIds(scan.idShapedRuns));
+    }
+    if (scan.rejected.length > 0) {
+        const classes = [...new Set(scan.rejected.map((row) => row.reason))].sort().join(", ");
+        parts.push(`${scan.rejected.length} keyword-anchored occurrence(s) refused by position (${classes})`);
+    }
+    parts.push(`accepted forms: ${ACCEPTED_CITATION_FORMS.join(" | ")}`);
+    return parts.join("; ");
+}
+function resolveCitedLean(citations, byCommentId, latestLean) {
+    if (latestLean !== undefined && citations.some((row) => row.id === latestLean.id)) {
+        return latestLean;
+    }
+    return citations
+        .map((row) => byCommentId.get(row.id))
+        .find((row) => row !== undefined && isSuccessorLeanBody(row.body));
+}
+/**
+ * Table resolution precedence (#3932).
+ *
+ * A typed `verified-claims table <id>` citation is the synthesis naming its own
+ * table, so it decides resolution: a generic citation neither satisfies it nor
+ * masks it. Scanning every citation for the first table-shaped body -- what
+ * this did before -- let an unrelated table-shaped comment clear a record whose
+ * claimed table is not a table, because the `missing-table-cite` refusal ran
+ * only after that untyped search failed.
+ *
+ * Cardinality rule: every table-kind claim must resolve to the same
+ * verified-claims table artifact. One valid typed claim must not launder an
+ * invalid one -- filtering to typed citations and then taking the first
+ * table-shaped body finds the real table in a valid-plus-ghost pair and never
+ * examines the ghost. `scanCitations` deduplicates on `(id, kind)`, so naming
+ * one table id twice is a single claim, while two distinct typed ids are two
+ * claims and cannot both be this record's table.
+ *
+ * With no typed claim the generic scan stands unchanged: permalink and bare
+ * `comment` citations scan as kind `comment`, and that is the published form
+ * these records use. Narrowing the citation contract so a table must be named
+ * by keyword is a separate decision needing its own migration criteria.
+ */
+function resolveCitedTable(citations, byCommentId) {
+    const claimed = citations.filter((row) => row.kind === "table");
+    if (claimed.length === 0) {
+        return {
+            ok: true,
+            table: citations
+                .map((row) => byCommentId.get(row.id))
+                .find((row) => row !== undefined && isVerifiedClaimsTableBody(row.body)),
+        };
+    }
+    const resolved = claimed.map((row) => ({ id: row.id, cited: byCommentId.get(row.id) }));
+    const unresolved = resolved.filter((row) => row.cited === undefined || !isVerifiedClaimsTableBody(row.cited.body));
+    if (unresolved.length > 0) {
+        return {
+            ok: false,
+            reason: "missing-table-cite",
+            detail: "synthesis cites a verified-claims table id that is not a table on this thread: " +
+                renderIds(unresolved.map((row) => row.id)),
+        };
+    }
+    const distinct = [...new Set(claimed.map((row) => row.id))];
+    if (distinct.length > 1) {
+        return {
+            ok: false,
+            reason: "ambiguous-table-cite",
+            detail: "synthesis claims more than one verified-claims table; every table citation must name " +
+                "the same table: " +
+                renderIds(distinct),
+        };
+    }
+    return { ok: true, table: resolved.find((row) => row.cited !== undefined)?.cited };
+}
+function verdictForSynthesis(comment, comments) {
+    const scan = scanCitations(comment.body);
+    const citations = scan.citations;
+    if (citations.length === 0) {
+        return {
+            status: "blocked",
+            reason: "lone-shape",
+            detail: loneShapeDetail(scan),
+        };
+    }
+    const byCommentId = byId(comments);
+    const citedLean = resolveCitedLean(citations, byCommentId, latestSuccessorLean(comments));
+    if (citedLean === undefined) {
+        return {
+            status: "blocked",
+            reason: "cite-not-lean",
+            detail: "no cited id is a successor lean on this thread; cited: " +
+                renderIds(citations.map((row) => row.id)),
+        };
+    }
+    const citedTable = resolveCitedTable(citations, byCommentId);
+    if (!citedTable.ok) {
+        return { status: "blocked", reason: citedTable.reason, detail: citedTable.detail };
+    }
+    return {
+        status: "complete",
+        synthesisCommentId: comment.id,
+        citedLeanId: citedLean.id,
+        citedTableId: citedTable.table?.id ?? null,
+    };
+}
+/**
+ * Ingest clearance from thread structure. Labels and author identity are not
+ * predicates. A lone synthesis-accepted sentence shape is not the record.
+ * Clearance cites the latest successor lean; an older complete record does not
+ * clear a later recut. A panel-deposit is in-flight even before critic posts.
+ */
+export function evaluateCompletedArcRecord(input) {
+    const comments = input.comments;
+    const labels = input.labels ?? [];
+    const synthesis = comments.filter((c) => isSynthesisAcceptedShape(c.body));
+    const completeRecords = synthesis
+        .map((comment) => verdictForSynthesis(comment, comments))
+        .filter((verdict) => {
+        return verdict.status === "complete";
+    });
+    if (completeRecords.length > 0) {
+        const latestLean = latestSuccessorLean(comments);
+        const matching = latestLean === undefined
+            ? completeRecords
+            : completeRecords.filter((record) => record.citedLeanId === latestLean.id);
+        if (matching.length > 0) {
+            return matching.reduce((a, b) => (a.synthesisCommentId >= b.synthesisCommentId ? a : b));
+        }
+        const latestCompleteId = completeRecords.reduce((max, record) => Math.max(max, record.synthesisCommentId), 0);
+        const laterSynthesis = synthesis.filter((comment) => comment.id > latestCompleteId);
+        if (laterSynthesis.length > 0) {
+            const latest = laterSynthesis.reduce((a, b) => (a.id >= b.id ? a : b));
+            return verdictForSynthesis(latest, comments);
+        }
+        const citedLeanIds = completeRecords.map((record) => record.citedLeanId);
+        const latestLeanId = latestLean === undefined ? "unknown" : String(latestLean.id);
+        return {
+            status: "blocked",
+            reason: "missing-record",
+            detail: `no completed-arc record cites the latest successor lean ${latestLeanId} on this thread; ` +
+                `existing record(s) cite lean ${renderIds(citedLeanIds)}; ` +
+                `ingest waits on a record citing lean ${latestLeanId}`,
+        };
+    }
+    if (synthesis.length > 0) {
+        const latest = synthesis.reduce((a, b) => (a.id >= b.id ? a : b));
+        return verdictForSynthesis(latest, comments);
+    }
+    const inArc = hasDesignCritiqueCatalogChip(labels) || isInFlightCritiqueThread(comments);
+    if (!inArc) {
+        return { status: "not-in-arc" };
+    }
+    return {
+        status: "blocked",
+        reason: "missing-record",
+        detail: "design-critique is in flight but the completed-arc record is missing: " +
+            "`design-critique: synthesis accepted, because ...` citing the accepted successor lean; " +
+            `accepted forms: ${ACCEPTED_CITATION_FORMS.join(" | ")}`,
+    };
+}
+export function assertCompletedArcAllowsIngest(input) {
+    const verdict = evaluateCompletedArcRecord(input);
+    if (verdict.status === "blocked") {
+        throw new DesignCritiqueIngestBlockedError(input.issueNumber, verdict.reason, verdict.detail);
+    }
+    return verdict;
+}
+//# sourceMappingURL=completed-arc-record.js.map

package/dist/freshness/bind.d.ts

@@ -3,7 +3,7 @@
  *
  * Host-agnostic storage:
  * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
- * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ * - With sessionId: `.deft/session-binds/<sha256-slice>.json` — isolated multi-session binds.
  *
  * Multi-agent hosts MUST pass a stable host session identity when binding and
  * reporting so one session cannot certify another as current.
@@ -16,10 +16,39 @@ export declare const SESSION_BINDS_DIR_REL: string;
 export declare function sessionBindPath(projectRoot: string, sessionId?: string | null): string;
 /**
  * Stable filesystem-safe file name for a host session id.
- * Keeps a short prefix for debug, hashes the rest to avoid path injection.
- * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ *
+ * Hash only (#3768): a 24-hex SHA-256 slice of the id. Hex cannot carry a path
+ * separator, so path injection is structurally impossible, and the name stays
+ * derivable from the id — lookup is one computed path, never a directory scan.
+ *
+ * Records written before #3768 also carried the first 32 characters of the id
+ * (`legacySessionFileName`). Dropping that prefix is hygiene, not a security
+ * fix: the same id is already published in `.deft/occupancy.json`,
+ * `.deft/ritual-state.json` and the bind record body (#3611 / #3754).
+ *
+ * Coupling warning: if `.deft/` JSON bodies are ever tightened (say to `0600`)
+ * while names still carry the prefix, the prefix becomes independently
+ * load-bearing — directory read permission alone would recover an id that the
+ * file mode was meant to protect. Anyone tightening those modes must keep bind
+ * names prefix-free.
  */
 export declare function safeSessionFileName(sessionId: string): string;
+/**
+ * Pre-#3768 record name: sanitized 32-character id prefix plus the same hash.
+ *
+ * Existing records are **tolerated, not migrated**. `readBoundGeneration` falls
+ * back to this name when the hash-only record is absent, so freshness pins
+ * written before the rename are not orphaned; writes always use the hash-only
+ * name, so the next bind supersedes the legacy record. Both names derive from
+ * the id, so the fallback stays O(1) and adds no directory scan.
+ *
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export declare function legacySessionFileName(sessionId: string): string;
+/**
+ * Derived path of a pre-#3768 record. Read fallback only — never a write target.
+ */
+export declare function legacySessionBindPath(projectRoot: string, sessionId: string): string;
 export interface BindSessionOptions {
     readonly sessionId?: string | null;
     readonly nowIso?: string;

package/dist/freshness/bind.js

@@ -3,7 +3,7 @@
  *
  * Host-agnostic storage:
  * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
- * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ * - With sessionId: `.deft/session-binds/<sha256-slice>.json` — isolated multi-session binds.
  *
  * Multi-agent hosts MUST pass a stable host session identity when binding and
  * reporting so one session cannot certify another as current.
@@ -26,14 +26,44 @@ export function sessionBindPath(projectRoot, sessionId) {
     }
     return join(root, SESSION_BINDS_DIR_REL, safeSessionFileName(id));
 }
+function sessionIdHash(sessionId) {
+    return createHash("sha256").update(sessionId.trim(), "utf8").digest("hex").slice(0, 24);
+}
 /**
  * Stable filesystem-safe file name for a host session id.
- * Keeps a short prefix for debug, hashes the rest to avoid path injection.
- * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ *
+ * Hash only (#3768): a 24-hex SHA-256 slice of the id. Hex cannot carry a path
+ * separator, so path injection is structurally impossible, and the name stays
+ * derivable from the id — lookup is one computed path, never a directory scan.
+ *
+ * Records written before #3768 also carried the first 32 characters of the id
+ * (`legacySessionFileName`). Dropping that prefix is hygiene, not a security
+ * fix: the same id is already published in `.deft/occupancy.json`,
+ * `.deft/ritual-state.json` and the bind record body (#3611 / #3754).
+ *
+ * Coupling warning: if `.deft/` JSON bodies are ever tightened (say to `0600`)
+ * while names still carry the prefix, the prefix becomes independently
+ * load-bearing — directory read permission alone would recover an id that the
+ * file mode was meant to protect. Anyone tightening those modes must keep bind
+ * names prefix-free.
  */
 export function safeSessionFileName(sessionId) {
+    return `${sessionIdHash(sessionId)}.json`;
+}
+/**
+ * Pre-#3768 record name: sanitized 32-character id prefix plus the same hash.
+ *
+ * Existing records are **tolerated, not migrated**. `readBoundGeneration` falls
+ * back to this name when the hash-only record is absent, so freshness pins
+ * written before the rename are not orphaned; writes always use the hash-only
+ * name, so the next bind supersedes the legacy record. Both names derive from
+ * the id, so the fallback stays O(1) and adds no directory scan.
+ *
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export function legacySessionFileName(sessionId) {
     const trimmed = sessionId.trim();
-    const hash = createHash("sha256").update(trimmed, "utf8").digest("hex").slice(0, 24);
+    const hash = sessionIdHash(trimmed);
     let prefix = "";
     for (let i = 0; i < trimmed.length && prefix.length < 32; i++) {
         const ch = trimmed[i] ?? "";
@@ -60,6 +90,12 @@ export function safeSessionFileName(sessionId) {
     const base = prefix.length > 0 ? `${prefix}-${hash}` : hash;
     return `${base}.json`;
 }
+/**
+ * Derived path of a pre-#3768 record. Read fallback only — never a write target.
+ */
+export function legacySessionBindPath(projectRoot, sessionId) {
+    return join(resolve(projectRoot), SESSION_BINDS_DIR_REL, legacySessionFileName(sessionId));
+}
 function nowIsoDefault() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -108,12 +144,7 @@ export function parseBoundGeneration(raw) {
         ...(payloadLoaded ? { payloadLoaded: true } : {}),
     };
 }
-/** Read the session bind record (null when absent/unreadable). */
-export function readBoundGeneration(projectRoot, options = {}) {
-    const path = sessionBindPath(projectRoot, options.sessionId);
-    if (!existsSync(path)) {
-        return null;
-    }
+function readBoundAt(path, wantSessionId) {
     try {
         const text = readFileSync(path, "utf8");
         const bound = parseBoundGeneration(JSON.parse(text));
@@ -122,8 +153,7 @@ export function readBoundGeneration(projectRoot, options = {}) {
         }
         // When reading a session-scoped bind, refuse a record whose embedded
         // sessionId disagrees (tamper / wrong file).
-        const want = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
-        if (want.length > 0 && bound.sessionId && bound.sessionId !== want) {
+        if (wantSessionId.length > 0 && bound.sessionId && bound.sessionId !== wantSessionId) {
             return null;
         }
         return bound;
@@ -132,6 +162,22 @@ export function readBoundGeneration(projectRoot, options = {}) {
         return null;
     }
 }
+/** Read the session bind record (null when absent/unreadable). */
+export function readBoundGeneration(projectRoot, options = {}) {
+    const want = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
+    const path = sessionBindPath(projectRoot, options.sessionId);
+    if (existsSync(path)) {
+        return readBoundAt(path, want);
+    }
+    if (want.length === 0) {
+        return null;
+    }
+    // Pre-#3768 records are tolerated, not migrated: one extra derived path and
+    // still no directory scan, so pins written under the old name resolve until
+    // the next bind supersedes them.
+    const legacy = legacySessionBindPath(projectRoot, want);
+    return existsSync(legacy) ? readBoundAt(legacy, want) : null;
+}
 function writeBoundAt(projectRoot, bound, sessionId) {
     const root = resolve(projectRoot);
     const target = sessionBindPath(projectRoot, sessionId);

package/dist/hooks/classify/host-session-identity.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Cooperative host-session identity and exact lifecycle-command rewriting (#3611).
+ *
+ * This is payload/environment classification, not authentication. Host hook JSON
+ * is locally forgeable under the occupancy model's cooperating-process
+ * assumption. The provider table and the canonical owner form live in
+ * `session/host-session-owner.ts` because the CLI claim path resolves the same
+ * owner from the same host (#3873).
+ */
+import { ambientHostSessionOwner, HOST_IDENTITY_PROVIDERS, type HookHostIdentityProvider, type HookHostIdentitySource, hookHostIdentitySource, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES } from "../../session/host-session-owner.js";
+export { ambientHostSessionOwner, HOST_IDENTITY_PROVIDERS, type HookHostIdentityProvider, type HookHostIdentitySource, hookHostIdentitySource, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, };
+export type HookHostIdentityStatus = "ok" | "missing" | "invalid" | "conflict" | "unsupported";
+export type HookHostIdentityResolution = {
+    readonly status: "ok";
+    readonly provider: HookHostIdentityProvider;
+    readonly rawSessionId: string;
+    readonly sessionId: string;
+    readonly message: null;
+} | {
+    readonly status: Exclude<HookHostIdentityStatus, "ok">;
+    readonly provider: string;
+    readonly rawSessionId: null;
+    readonly sessionId: null;
+    readonly message: string;
+};
+/**
+ * Resolve the stable conversation/session-family key documented by each host.
+ *
+ * - Codex: payload `session_id` (parent and subagents share it).
+ * - Claude Code: payload `session_id` (`agent_id` is not the owner key).
+ * - Cursor: payload `conversation_id`; simultaneous `session_id` must agree.
+ * - Grok: hook process `GROK_SESSION_ID` (#3873). The payload `session_id` is
+ *   deliberately not read -- that contract is unverified.
+ * - Unknown hosts: no guessed identity; callers keep the explicit/env flow.
+ */
+export declare function resolveHookHostIdentity(host: string, payload: unknown, environ?: NodeJS.ProcessEnv): HookHostIdentityResolution;
+/**
+ * True when a `host-env` provider simply did not publish its variable (#3873).
+ *
+ * Absence is the pre-#3873 state rather than a broken contract, so callers keep
+ * the documented explicit `--session-id` / `DEFT_SESSION_ID` flow instead of
+ * failing a host that never had a hook identity to begin with. It is never an
+ * admission: with no explicit owner the actor stays unset and the write gate
+ * still denies. A present-but-malformed variable is `invalid` and fails closed.
+ */
+export declare function hostIdentityFallsBackToExplicitOwner(host: string, resolution: HookHostIdentityResolution): boolean;
+export declare const EXACT_LIFECYCLE_VERBS: readonly ["session:start", "session:ready", "session:end", "occupancy:steal", "occupancy:release", "occupancy:heartbeat", "swarm:launch"];
+export type ExactLifecycleVerb = (typeof EXACT_LIFECYCLE_VERBS)[number];
+export interface ExactLifecycleCommandRewrite {
+    readonly kind: "rewrite";
+    readonly verb: ExactLifecycleVerb;
+    readonly originalCommand: string;
+    readonly rewrittenCommand: string;
+    readonly updatedInput: Record<string, unknown>;
+}
+export interface ExactLifecycleCommandConflict {
+    readonly kind: "conflict";
+    readonly verb: ExactLifecycleVerb;
+    readonly existingSessionId: string;
+    readonly requestedSessionId: string;
+    readonly message: string;
+}
+export type ExactLifecycleCommandResult = ExactLifecycleCommandRewrite | ExactLifecycleCommandConflict | null;
+/** Logical lifecycle verb for one exact, simple shell command; otherwise null. */
+export declare function exactLifecycleCommandVerb(payload: unknown): ExactLifecycleVerb | null;
+interface SessionIdArgs {
+    readonly status: "absent" | "present" | "invalid";
+    readonly values: readonly string[];
+}
+export interface ExactLifecycleCommandInspection {
+    readonly verb: ExactLifecycleVerb;
+    readonly task: boolean;
+    readonly rewriteSafe: boolean;
+    readonly requiresOwner: boolean;
+    readonly sessionIdStatus: SessionIdArgs["status"];
+    readonly sessionId: string | null;
+}
+/** Inspect one exact lifecycle command without requiring a host identity. */
+export declare function inspectExactLifecycleCommand(payload: unknown): ExactLifecycleCommandInspection | null;
+/**
+ * Append a canonical host owner to one exact Directive lifecycle command.
+ *
+ * The returned `updatedInput` is a complete shallow clone of the original
+ * host tool input. `null` means no safe rewrite. An explicit foreign identity
+ * is surfaced as a conflict so dispatcher wiring can deny instead of replacing
+ * operator input.
+ */
+export declare function rewriteExactLifecycleCommand(payload: unknown, sessionId: string): ExactLifecycleCommandResult;
+//# sourceMappingURL=host-session-identity.d.ts.map