@deftai/directive-core 0.98.1 → 0.100.0

package/dist/literal-acceptance/safety.js

@@ -0,0 +1,251 @@
+/**
+ * Safety filters for literal acceptance commands (#3267 Greptile P1).
+ *
+ * Stored commands may originate from issue text. Before shell execution they
+ * MUST pass an allowlist of argv-shaped CLI invocations without shell metacharacters.
+ * source=task_statement is capture-only until agent promotes to verify_commands.
+ *
+ * Wrapper verbs (task/deft/directive) and package managers are further restricted
+ * to read-only / verification subcommands so ambient credentials and lifecycle
+ * mutations cannot ride an acceptance command (#3267 residual).
+ */
+import { EXECUTABLE_LITERAL_SOURCES } from "./types.js";
+/** Characters that imply shell composition / expansion (refuse closed). */
+const SHELL_META_CHARS = new Set([
+    ";",
+    "|",
+    "&",
+    "`",
+    "\n",
+    "\r",
+    "<",
+    ">",
+    "(",
+    ")",
+    "{",
+    "}",
+    "$",
+    "\0",
+]);
+/**
+ * First-token allowlist for **execution** (#3267 Greptile P1 ambient-authority).
+ * Network/SCM tools (curl/gh/git/docker) are intentionally excluded — they retain
+ * ambient credentials. Capture may still record broader CLI shape; only these
+ * tokens may spawn, and wrappers/PMs require subcommand allowlists below.
+ */
+const ALLOWED_FIRST_TOKENS = new Set([
+    "task",
+    "deft",
+    "directive",
+    "pnpm",
+    "npm",
+    "npx",
+    "yarn",
+    "bun",
+    "vitest",
+    "true",
+    "false",
+]);
+/**
+ * Exact wrapper subcommands that are verification-shaped (no scope/policy/scm/swarm
+ * mutations). Additional args after these tokens are allowed (e.g. `task check --json`).
+ */
+const ALLOWED_WRAPPER_SUBCOMMANDS = new Set([
+    "check",
+    "doctor",
+    "help",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+    "test",
+]);
+/**
+ * Prefixes for wrapper verbs that stay on the verify/read surface.
+ * `verify:` / `verify-` cover task verify:* family; bare `verify ` is the space form.
+ */
+const ALLOWED_WRAPPER_PREFIXES = ["verify:", "verify-", "verify "];
+/** Whether this provenance is allowed to spawn a shell (#3267). */
+export function isExecutableLiteralSource(source) {
+    return EXECUTABLE_LITERAL_SOURCES.includes(source);
+}
+/**
+ * Linear-time scan: refuse shell metacharacters and non-allowlisted first tokens.
+ * Intentionally does not parse full shell grammar — fail closed on ambiguity.
+ */
+export function evaluateCommandSafety(command) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+        return { ok: false, reason: "empty command" };
+    }
+    const trimmed = command.trim();
+    if (trimmed.length > 500) {
+        return { ok: false, reason: "command exceeds 500 characters" };
+    }
+    for (let i = 0; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (SHELL_META_CHARS.has(ch)) {
+            return {
+                ok: false,
+                reason: `shell metacharacter ${JSON.stringify(ch)} is not allowed in literal AC commands`,
+            };
+        }
+    }
+    let end = 0;
+    while (end < trimmed.length && trimmed[end] !== " " && trimmed[end] !== "\t") {
+        end += 1;
+    }
+    const first = trimmed.slice(0, end).toLowerCase();
+    if (first.includes("/") || first.includes("\\") || first.includes(":")) {
+        return { ok: false, reason: "path-like first token is not allowlisted" };
+    }
+    if (!ALLOWED_FIRST_TOKENS.has(first)) {
+        return {
+            ok: false,
+            reason: `first token ${JSON.stringify(first)} is not in the literal-AC allowlist`,
+        };
+    }
+    const rest = trimmed.slice(end).trim();
+    // Framework wrappers: only verification / help / version subcommands (no scope/policy/merge).
+    if (first === "task" || first === "deft" || first === "directive") {
+        return evaluateWrapperSubcommand(rest);
+    }
+    // Package managers: only test/exec vitest/run test|check|--version (no install/publish/net).
+    // npx is stricter (no run/exec registry forms) — see evaluatePackageManagerArgs.
+    if (first === "pnpm" ||
+        first === "npm" ||
+        first === "npx" ||
+        first === "yarn" ||
+        first === "bun") {
+        return evaluatePackageManagerArgs(rest, first);
+    }
+    // vitest first-token: allow run / related test args only (no watch/ui).
+    if (first === "vitest") {
+        return evaluateVitestArgs(rest);
+    }
+    return { ok: true, reason: null };
+}
+/**
+ * Restrict task/deft/directive to verification-shaped subcommands.
+ * Fail closed on scope/policy/swarm/pr/scm/lifecycle mutations.
+ */
+function evaluateWrapperSubcommand(rest) {
+    if (rest.length === 0) {
+        return {
+            ok: false,
+            reason: "wrapper verb (task/deft/directive) requires a restricted verification subcommand",
+        };
+    }
+    const low = rest.toLowerCase();
+    // First subcommand token (before flags/args).
+    let subEnd = 0;
+    while (subEnd < low.length && low[subEnd] !== " " && low[subEnd] !== "\t") {
+        subEnd += 1;
+    }
+    const sub = low.slice(0, subEnd);
+    if (ALLOWED_WRAPPER_SUBCOMMANDS.has(sub)) {
+        return { ok: true, reason: null };
+    }
+    for (const prefix of ALLOWED_WRAPPER_PREFIXES) {
+        if (low.startsWith(prefix)) {
+            return { ok: true, reason: null };
+        }
+    }
+    return {
+        ok: false,
+        reason: "wrapper subcommand must be check|doctor|verify:*|help|--version " +
+            "(scope/policy/swarm/scm/merge and other ambient-authority verbs denied)",
+    };
+}
+/**
+ * Package-manager subcommand allowlist (no install/publish/exec of arbitrary bins).
+ * `npx` is stricter than npm/pnpm/yarn/bun: it must not accept `run`/`exec` forms that
+ * resolve arbitrary registry packages with inherited env (Greptile conf residual).
+ */
+function evaluatePackageManagerArgs(rest, firstToken) {
+    if (rest.length === 0) {
+        return { ok: false, reason: "package manager requires a restricted subcommand" };
+    }
+    const low = rest.toLowerCase();
+    // npx: only vitest (direct) or version/help — no `npx run` / `npx exec <pkg>` registry path.
+    if (firstToken === "npx") {
+        if (low === "--version" || low === "-v" || low === "--help" || low === "-h") {
+            return { ok: true, reason: null };
+        }
+        if (low === "vitest" || low.startsWith("vitest ")) {
+            const after = low === "vitest" ? "" : low.slice("vitest".length).trim();
+            return evaluateVitestArgs(after);
+        }
+        return {
+            ok: false,
+            reason: "npx is limited to vitest|--version|--help " +
+                "(npx run/exec/registry packages denied for ambient-authority)",
+        };
+    }
+    // exec: only vitest (not deft/task — those re-open wrapper ambient authority).
+    if (low.startsWith("exec ")) {
+        const afterExec = low.slice("exec ".length).trim();
+        if (afterExec === "vitest" || afterExec.startsWith("vitest ")) {
+            const after = afterExec === "vitest" ? "" : afterExec.slice("vitest".length).trim();
+            return evaluateVitestArgs(after);
+        }
+        return {
+            ok: false,
+            reason: "package-manager exec is limited to vitest " +
+                "(exec of deft/task/other bins denied for ambient-authority)",
+        };
+    }
+    if (low.startsWith("run vitest")) {
+        const after = low.slice("run vitest".length).trim();
+        return evaluateVitestArgs(after.length > 0 ? `run ${after}` : "run");
+    }
+    const allowedPm = low === "test" ||
+        low === "--version" ||
+        low === "-v" ||
+        low.startsWith("test ") ||
+        low.startsWith("run test") ||
+        low.startsWith("run check");
+    if (!allowedPm) {
+        return {
+            ok: false,
+            reason: "package-manager args must be test|exec vitest|run test|run check|--version " +
+                "(arbitrary scripts/network install denied for ambient-authority)",
+        };
+    }
+    return { ok: true, reason: null };
+}
+/**
+ * Vitest args: only non-interactive run paths. Deny watch/ui/browser hang modes.
+ */
+function evaluateVitestArgs(rest) {
+    const low = rest.trim().toLowerCase();
+    if (low.length === 0) {
+        // bare `vitest` defaults to watch in many setups — refuse closed.
+        return {
+            ok: false,
+            reason: "vitest requires explicit run (bare vitest defaults to watch; denied)",
+        };
+    }
+    for (const bad of ["watch", "ui", "browser", "--watch", "--ui", "--browser", "dev"]) {
+        if (low === bad ||
+            low.startsWith(`${bad} `) ||
+            low.endsWith(` ${bad}`) ||
+            low.includes(` ${bad} `)) {
+            return {
+                ok: false,
+                reason: `vitest ${bad} is denied (hang/interactive mode; use run)`,
+            };
+        }
+    }
+    if (low === "run" ||
+        low.startsWith("run ") ||
+        low === "--version" ||
+        low === "-v" ||
+        low.startsWith("--run")) {
+        return { ok: true, reason: null };
+    }
+    return {
+        ok: false,
+        reason: "vitest args must be run|--version (watch/ui/network denied for ambient-authority)",
+    };
+}
+//# sourceMappingURL=safety.js.map

package/dist/literal-acceptance/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands from the task statement at intake;
+ * run them verbatim before done. Self-chosen verification is supplementary.
+ * Extends #973 machine-verifiable-spec. Survives ceremony dial rapid/minimal
+ * (#3214) — verification depth is constant (#3156).
+ */
+/** Where a literal command was recovered from. */
+export type LiteralAcceptanceSource = "task_statement" | "verify_commands" | "plan_item" | "explicit" | "metadata";
+/**
+ * Sources trusted for automatic shell execution (#3267 Greptile P1).
+ * `task_statement` (raw issue/task text) is capture-only until an agent promotes
+ * the exact command into swarm.verify_commands / plan item / explicit metadata.
+ */
+export declare const EXECUTABLE_LITERAL_SOURCES: readonly LiteralAcceptanceSource[];
+/**
+ * One executable acceptance command exactly as stated (no paraphrase).
+ * `command` is the shell string to run with the same flags/cwd as written.
+ */
+export interface LiteralAcceptanceCommand {
+    /** Exact command string from the task statement (not reworded). */
+    readonly command: string;
+    /**
+     * Working directory relative to project root when stated; null/omit = project root.
+     * Absolute paths are allowed when the statement uses them.
+     */
+    readonly cwd?: string | null;
+    /** Expected stdout substring when the statement names expected output. */
+    readonly expectedStdout?: string | null;
+    /** Expected process exit code (default 0). */
+    readonly expectedExitCode?: number;
+    readonly source: LiteralAcceptanceSource;
+    /** Short provenance (heading, field path, or line context). */
+    readonly sourceSpan?: string | null;
+}
+/** Result of running one stored command. */
+export interface LiteralAcceptanceRunResult {
+    readonly command: string;
+    readonly cwd: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/**
+ * Shell-shaped command that was refused by the safety allowlist (#3267 residual).
+ * Operators must see these — silent drop hides ambient-authority / shape mistakes.
+ */
+export interface RejectedLiteralCommand {
+    readonly command: string;
+    readonly reason: string;
+    readonly sourceSpan?: string | null;
+}
+/** Aggregate evaluate / done-gate result. */
+export interface LiteralAcceptanceGateResult {
+    readonly ok: boolean;
+    /** 0 = pass or no commands; 1 = command failed; 2 = config / input error. */
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    readonly runs: readonly LiteralAcceptanceRunResult[];
+    /** Safety-rejected shell-shaped lines (fail-loud ledger; may be empty). */
+    readonly rejected?: readonly RejectedLiteralCommand[];
+}
+/** Metadata key for operator-visible rejected command ledger (#3267). */
+export declare const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY: "literal_acceptance_rejected";
+/** Injectable shell runner for tests (default: spawnSync shell). */
+export type LiteralAcceptanceRunner = (input: {
+    readonly command: string;
+    readonly cwd: string;
+}) => {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+/** Metadata key on plan.metadata for captured literal commands (#3267). */
+export declare const LITERAL_ACCEPTANCE_METADATA_KEY: "literal_acceptance_commands";
+/** Alternate camelCase key accepted on read. */
+export declare const LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL: "literalAcceptanceCommands";
+//# sourceMappingURL=types.d.ts.map

package/dist/literal-acceptance/types.js

@@ -0,0 +1,26 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands from the task statement at intake;
+ * run them verbatim before done. Self-chosen verification is supplementary.
+ * Extends #973 machine-verifiable-spec. Survives ceremony dial rapid/minimal
+ * (#3214) — verification depth is constant (#3156).
+ */
+/**
+ * Sources trusted for automatic shell execution (#3267 Greptile P1).
+ * `task_statement` (raw issue/task text) is capture-only until an agent promotes
+ * the exact command into swarm.verify_commands / plan item / explicit metadata.
+ */
+export const EXECUTABLE_LITERAL_SOURCES = [
+    "verify_commands",
+    "plan_item",
+    "explicit",
+    "metadata",
+];
+/** Metadata key for operator-visible rejected command ledger (#3267). */
+export const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY = "literal_acceptance_rejected";
+/** Metadata key on plan.metadata for captured literal commands (#3267). */
+export const LITERAL_ACCEPTANCE_METADATA_KEY = "literal_acceptance_commands";
+/** Alternate camelCase key accepted on read. */
+export const LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL = "literalAcceptanceCommands";
+//# sourceMappingURL=types.js.map

package/dist/platform/host-content-surface.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Host content-surface class + managed-section drift (#3162).
+ *
+ * Directive file gates and #830/#2508 pins assume filesystem-visible work product
+ * and a host that does not rewrite constitution mid-run. REPL-first and
+ * self-mutating hosts break those assumptions. This module classifies the host
+ * surface (capability pointer #1461/#1357) and reports managed AGENTS section
+ * drift without inventing a full pin product.
+ *
+ * Never blocks session-start — advisory only.
+ */
+import { type AgentsMdSeams } from "./agents-md.js";
+/** Host content-surface classes for gate / pin honesty (#3162). */
+export declare const HOST_CONTENT_SURFACE_CLASSES: readonly ["file-first", "repl-first", "self-mutating", "unknown"];
+export type HostContentSurfaceClass = (typeof HOST_CONTENT_SURFACE_CLASSES)[number];
+/** Env key for explicit class override (capability descriptor pointer). */
+export declare const ENV_HOST_CONTENT_SURFACE = "DEFT_HOST_CONTENT_SURFACE";
+/** Env opt-in: host holds executable work product before files exist. */
+export declare const ENV_HOST_REPL_FIRST = "DEFT_HOST_REPL_FIRST";
+/** Env opt-in: host refine/kernel may CRUD skills/prompts mid-run. */
+export declare const ENV_HOST_SELF_MUTATE = "DEFT_HOST_SELF_MUTATE";
+export interface HostContentSurfaceClassResult {
+    readonly contentClass: HostContentSurfaceClass;
+    readonly source: string;
+    /** Signals observed (env keys present). */
+    readonly signals: readonly string[];
+}
+export type ManagedSectionDriftState = "current" | "stale" | "missing" | "absent" | "unreadable" | "template-missing" | "template-malformed" | "unknown";
+export interface ManagedSectionDriftReport {
+    readonly state: ManagedSectionDriftState;
+    readonly embeddedSha: string | null;
+    /** SHA-256 (12 hex) of stripped managed-section body when readable. */
+    readonly bodyHash: string | null;
+    readonly path: string;
+}
+export interface HostContentSurfaceReport {
+    readonly contentClass: HostContentSurfaceClass;
+    readonly classSource: string;
+    readonly signals: readonly string[];
+    readonly managedSection: ManagedSectionDriftReport;
+    /** Runtime mode from platform capability descriptor when provided. */
+    readonly runtimeMode: string | null;
+}
+export interface HostContentSurfaceSeams {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    readonly agentsMdSeams?: AgentsMdSeams;
+    readonly runtimeMode?: string | null;
+}
+/**
+ * Classify host content surface from explicit env / capability signals (#1461/#1357 pointer).
+ * Defaults to file-first (historical Directive assumption) when no signal is set.
+ */
+export declare function classifyHostContentSurface(environ?: Readonly<Record<string, string | undefined>>): HostContentSurfaceClassResult;
+/**
+ * Probe managed AGENTS.md section drift (tamper-evident boundary, not full #830 pins).
+ * Uses agents:refresh plan state + embedded marker sha + body hash.
+ */
+export declare function probeManagedSectionDrift(projectRoot: string, seams?: HostContentSurfaceSeams): ManagedSectionDriftReport;
+/** Full host-surface report for session-start payload + lines. */
+export declare function probeHostContentSurface(projectRoot: string, seams?: HostContentSurfaceSeams): HostContentSurfaceReport;
+export declare function hostContentSurfaceToDict(report: HostContentSurfaceReport): Record<string, unknown>;
+/**
+ * Format operator-facing host-surface lines (#3162).
+ * Always emits one summary line; adds honesty note for non-file-first or drift.
+ */
+export declare function formatHostContentSurfaceLines(report: HostContentSurfaceReport): string[];
+/**
+ * Probe + format; fail-open for session-start (never throws to callers that wrap).
+ */
+export declare function maybeFormatHostContentSurfaceLines(projectRoot: string, seams?: HostContentSurfaceSeams): {
+    report: HostContentSurfaceReport;
+    lines: string[];
+};
+//# sourceMappingURL=host-content-surface.d.ts.map

package/dist/platform/host-content-surface.js

@@ -0,0 +1,214 @@
+/**
+ * Host content-surface class + managed-section drift (#3162).
+ *
+ * Directive file gates and #830/#2508 pins assume filesystem-visible work product
+ * and a host that does not rewrite constitution mid-run. REPL-first and
+ * self-mutating hosts break those assumptions. This module classifies the host
+ * surface (capability pointer #1461/#1357) and reports managed AGENTS section
+ * drift without inventing a full pin product.
+ *
+ * Never blocks session-start — advisory only.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentsRefreshPlan, extractManagedSection, parseManagedSectionAttrs, stripManagedSectionAttrs, } from "./agents-md.js";
+/** Host content-surface classes for gate / pin honesty (#3162). */
+export const HOST_CONTENT_SURFACE_CLASSES = [
+    "file-first",
+    "repl-first",
+    "self-mutating",
+    "unknown",
+];
+/** Env key for explicit class override (capability descriptor pointer). */
+export const ENV_HOST_CONTENT_SURFACE = "DEFT_HOST_CONTENT_SURFACE";
+/** Env opt-in: host holds executable work product before files exist. */
+export const ENV_HOST_REPL_FIRST = "DEFT_HOST_REPL_FIRST";
+/** Env opt-in: host refine/kernel may CRUD skills/prompts mid-run. */
+export const ENV_HOST_SELF_MUTATE = "DEFT_HOST_SELF_MUTATE";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function envTruthy(value) {
+    return TRUTHY.has((value ?? "").trim().toLowerCase());
+}
+function normalizeClassToken(raw) {
+    const token = raw.trim().toLowerCase().replace(/_/g, "-");
+    if (HOST_CONTENT_SURFACE_CLASSES.includes(token)) {
+        return token;
+    }
+    // Accept aliases used in host docs.
+    if (token === "file" || token === "filesystem" || token === "fs-first")
+        return "file-first";
+    if (token === "repl" || token === "kernel-first")
+        return "repl-first";
+    if (token === "self-edit" || token === "self-editing" || token === "continual-harness") {
+        return "self-mutating";
+    }
+    return null;
+}
+/**
+ * Classify host content surface from explicit env / capability signals (#1461/#1357 pointer).
+ * Defaults to file-first (historical Directive assumption) when no signal is set.
+ */
+export function classifyHostContentSurface(environ = process.env) {
+    const signals = [];
+    const explicit = (environ[ENV_HOST_CONTENT_SURFACE] ?? "").trim();
+    if (explicit) {
+        signals.push(ENV_HOST_CONTENT_SURFACE);
+        const parsed = normalizeClassToken(explicit);
+        if (parsed !== null) {
+            return {
+                contentClass: parsed,
+                source: `env:${ENV_HOST_CONTENT_SURFACE}`,
+                signals,
+            };
+        }
+        return {
+            contentClass: "unknown",
+            source: `env:${ENV_HOST_CONTENT_SURFACE}:unrecognized`,
+            signals,
+        };
+    }
+    const selfMutate = envTruthy(environ[ENV_HOST_SELF_MUTATE]);
+    const replFirst = envTruthy(environ[ENV_HOST_REPL_FIRST]);
+    if (selfMutate)
+        signals.push(ENV_HOST_SELF_MUTATE);
+    if (replFirst)
+        signals.push(ENV_HOST_REPL_FIRST);
+    // Self-mutating supersedes REPL-first when both are set (broader honesty surface).
+    if (selfMutate) {
+        return {
+            contentClass: "self-mutating",
+            source: `env:${ENV_HOST_SELF_MUTATE}`,
+            signals,
+        };
+    }
+    if (replFirst) {
+        return {
+            contentClass: "repl-first",
+            source: `env:${ENV_HOST_REPL_FIRST}`,
+            signals,
+        };
+    }
+    return {
+        contentClass: "file-first",
+        source: "assumed",
+        signals,
+    };
+}
+function hashBody(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
+}
+function mapPlanState(raw) {
+    if (typeof raw !== "string")
+        return "unknown";
+    switch (raw) {
+        case "current":
+        case "stale":
+        case "missing":
+        case "absent":
+        case "unreadable":
+        case "template-missing":
+        case "template-malformed":
+            return raw;
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Probe managed AGENTS.md section drift (tamper-evident boundary, not full #830 pins).
+ * Uses agents:refresh plan state + embedded marker sha + body hash.
+ */
+export function probeManagedSectionDrift(projectRoot, seams = {}) {
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const plan = agentsRefreshPlan(projectRoot, seams.agentsMdSeams ?? {});
+    const state = mapPlanState(plan.state);
+    let embeddedSha = null;
+    let bodyHash = null;
+    const readAgents = seams.agentsMdSeams?.readAgents ??
+        ((path) => {
+            try {
+                if (!existsSync(path))
+                    return null;
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    try {
+        const text = readAgents(agentsPath);
+        if (text !== null) {
+            const extracted = extractManagedSection(text);
+            if (extracted !== null) {
+                const attrs = parseManagedSectionAttrs(extracted);
+                embeddedSha = attrs?.sha ?? null;
+                bodyHash = hashBody(stripManagedSectionAttrs(extracted));
+            }
+        }
+    }
+    catch {
+        // body hash is best-effort
+    }
+    return {
+        state,
+        embeddedSha,
+        bodyHash,
+        path: typeof plan.path === "string" ? plan.path : agentsPath,
+    };
+}
+/** Full host-surface report for session-start payload + lines. */
+export function probeHostContentSurface(projectRoot, seams = {}) {
+    const environ = seams.environ ?? process.env;
+    const classified = classifyHostContentSurface(environ);
+    const managedSection = probeManagedSectionDrift(projectRoot, seams);
+    return {
+        contentClass: classified.contentClass,
+        classSource: classified.source,
+        signals: classified.signals,
+        managedSection,
+        runtimeMode: seams.runtimeMode ?? null,
+    };
+}
+export function hostContentSurfaceToDict(report) {
+    return {
+        content_class: report.contentClass,
+        class_source: report.classSource,
+        signals: [...report.signals],
+        runtime_mode: report.runtimeMode,
+        managed_section: {
+            state: report.managedSection.state,
+            embedded_sha: report.managedSection.embeddedSha,
+            body_hash: report.managedSection.bodyHash,
+            path: report.managedSection.path,
+        },
+    };
+}
+/**
+ * Format operator-facing host-surface lines (#3162).
+ * Always emits one summary line; adds honesty note for non-file-first or drift.
+ */
+export function formatHostContentSurfaceLines(report) {
+    const managed = report.managedSection.state;
+    const summary = `[deft host-surface] class=${report.contentClass} source=${report.classSource} ` +
+        `managed=${managed}` +
+        (report.managedSection.embeddedSha ? ` sha=${report.managedSection.embeddedSha}` : "") +
+        (report.managedSection.bodyHash ? ` body=${report.managedSection.bodyHash}` : "");
+    const lines = [summary];
+    if (report.contentClass === "repl-first" || report.contentClass === "self-mutating") {
+        lines.push("[deft host-surface] honesty: file gates and agent-only pins do not see host-kernel " +
+            "or mid-run host refine work product — see content/docs/host-surface-assumptions.md (#3162)");
+    }
+    if (managed === "stale" || managed === "missing" || managed === "absent") {
+        lines.push("[deft host-surface] managed AGENTS section drift — run `deft agents:refresh` " +
+            "(or `task agents:refresh`) so pins/managed constitution match the deposit");
+    }
+    return lines;
+}
+/**
+ * Probe + format; fail-open for session-start (never throws to callers that wrap).
+ */
+export function maybeFormatHostContentSurfaceLines(projectRoot, seams = {}) {
+    const report = probeHostContentSurface(projectRoot, seams);
+    return { report, lines: formatHostContentSurfaceLines(report) };
+}
+//# sourceMappingURL=host-content-surface.js.map

package/dist/platform/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";

package/dist/platform/index.js

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";