@deftai/directive-core 0.88.0 → 0.90.0

package/dist/doctor/openclaw-skills.d.ts

@@ -0,0 +1,109 @@
+/**
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ *
+ * When OpenClaw signals are present, doctor checks the main workspace skills
+ * root for the four always-pin skills (#2508). Missing pins emit a warning with
+ * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
+ * or copied from the installed content package into the target skills dir.
+ *
+ * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
+ */
+import type { OutputSink } from "./output.js";
+import type { DoctorSeams, Finding } from "./types.js";
+/** Stable doctor check id for JSON findings. */
+export declare const OPENCLAW_SKILL_PINS_CHECK = "openclaw-skill-pins";
+/** Always-pin skill directory names (#2508 / cold-start). */
+export declare const OPENCLAW_ALWAYS_PIN_SKILLS: readonly ["deft-directive-build", "deft-directive-pre-pr", "deft-directive-review-cycle", "deft-directive-swarm"];
+export type OpenClawAlwaysPinSkill = (typeof OPENCLAW_ALWAYS_PIN_SKILLS)[number];
+/** Env keys that count as strong OpenClaw signals (#3001). */
+export declare const OPENCLAW_ENV_SIGNAL_KEYS: readonly ["OPENCLAW", "DEFT_PROBE_OPENCLAW", "DEFT_AGENT_RUNTIME", "OPENCLAW_STATE_DIR"];
+export interface OpenClawSkillPinsSeams {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDir?: () => string;
+    readonly isDir?: (path: string) => boolean;
+    readonly isFile?: (path: string) => boolean;
+    readonly pathExists?: (path: string) => boolean;
+    readonly readDir?: (path: string) => string[];
+    readonly lstatKind?: (path: string) => "file" | "dir" | "symlink" | "other" | "missing";
+    readonly mkdirp?: (path: string) => void;
+    readonly symlinkDir?: (target: string, path: string) => void;
+    readonly copyDir?: (src: string, dst: string) => void;
+    readonly removePath?: (path: string) => void;
+    readonly contentRootFor?: (frameworkRoot: string) => string;
+    readonly isTty?: () => boolean;
+    readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
+}
+export interface OpenClawPinAssessment {
+    readonly skillsDir: string;
+    readonly present: readonly OpenClawAlwaysPinSkill[];
+    readonly missing: readonly OpenClawAlwaysPinSkill[];
+    readonly divergent: readonly OpenClawAlwaysPinSkill[];
+}
+export interface OpenClawDetectResult {
+    readonly detected: boolean;
+    readonly reasons: readonly string[];
+    readonly stateDir: string;
+    readonly mainSkillsDir: string;
+}
+export type PinInstallMethod = "symlink" | "copy" | "skipped" | "already-present";
+export interface PinInstallResult {
+    readonly skillId: OpenClawAlwaysPinSkill;
+    readonly method: PinInstallMethod;
+    readonly target: string;
+    readonly source: string;
+    readonly detail?: string;
+}
+/**
+ * Resolve OpenClaw state directory: OPENCLAW_STATE_DIR or ~/.openclaw.
+ */
+export declare function resolveOpenClawStateDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Main agent workspace skills root under the state dir.
+ */
+export declare function resolveMainSkillsDir(stateDir: string): string;
+/**
+ * Detect OpenClaw from env signals and/or presence of the state directory.
+ */
+export declare function detectOpenClaw(env?: NodeJS.ProcessEnv, options?: {
+    homeDir?: string;
+    isDir?: (path: string) => boolean;
+}): OpenClawDetectResult;
+/**
+ * List in-scope skills directories. Default: main only.
+ * With allAgents: main + every workspace- star /skills under the state dir.
+ */
+export declare function listInScopeSkillsDirs(stateDir: string, allAgents: boolean, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "readDir">): string[];
+/**
+ * Resolve content package skills/<id> for a pin.
+ */
+export declare function resolvePinSourceDir(contentBase: string, skillId: string): string;
+/**
+ * Assess which always-pins are present / missing / divergent in a skills root.
+ *
+ * - present: directory (or symlink) with SKILL.md
+ * - missing: path does not exist
+ * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ */
+export declare function assessOpenClawPins(skillsDir: string, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "isFile" | "pathExists" | "lstatKind">): OpenClawPinAssessment;
+/**
+ * Install one pin into a skills root. Prefer symlink; copy on failure.
+ * Never deletes user skills. Divergent targets require force or TTY confirm.
+ */
+export declare function installOpenClawPin(skillId: OpenClawAlwaysPinSkill, sourceDir: string, skillsDir: string, options?: {
+    force?: boolean;
+    allowOverwrite?: boolean;
+}, seams?: OpenClawSkillPinsSeams): PinInstallResult;
+export interface RunOpenClawSkillPinsOptions {
+    readonly frameworkRoot: string;
+    readonly fixMode: boolean;
+    readonly jsonMode: boolean;
+    readonly force: boolean;
+    readonly allAgents: boolean;
+    readonly seams?: DoctorSeams & OpenClawSkillPinsSeams;
+}
+/**
+ * Doctor check: detect OpenClaw + missing always-pins; optionally fix.
+ * No-ops when OpenClaw signals are absent.
+ */
+export declare function runOpenClawSkillPinsCheck(sink: OutputSink, addFinding: (finding: Finding) => void, options: RunOpenClawSkillPinsOptions): void;
+//# sourceMappingURL=openclaw-skills.d.ts.map

package/dist/doctor/openclaw-skills.js

@@ -0,0 +1,463 @@
+/**
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ *
+ * When OpenClaw signals are present, doctor checks the main workspace skills
+ * root for the four always-pin skills (#2508). Missing pins emit a warning with
+ * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
+ * or copied from the installed content package into the target skills dir.
+ *
+ * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { contentRoot } from "../content-root.js";
+/** Stable doctor check id for JSON findings. */
+export const OPENCLAW_SKILL_PINS_CHECK = "openclaw-skill-pins";
+/** Always-pin skill directory names (#2508 / cold-start). */
+export const OPENCLAW_ALWAYS_PIN_SKILLS = [
+    "deft-directive-build",
+    "deft-directive-pre-pr",
+    "deft-directive-review-cycle",
+    "deft-directive-swarm",
+];
+/** Env keys that count as strong OpenClaw signals (#3001). */
+export const OPENCLAW_ENV_SIGNAL_KEYS = [
+    "OPENCLAW",
+    "DEFT_PROBE_OPENCLAW",
+    "DEFT_AGENT_RUNTIME",
+    "OPENCLAW_STATE_DIR",
+];
+const DOC_OPENCLAW_HOST = "docs/openclaw-agent-host.md";
+const DOC_HOST_LIFECYCLE = "contracts/host-lifecycle-duties.md";
+const DOC_SKILL_PINS = "docs/skill-pin-policy.md";
+const REMEDIATION_FIX = "deft doctor --fix";
+const REMEDIATION_ALL_AGENTS = "deft doctor --fix --openclaw-all-agents";
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultPathExists(path) {
+    return existsSync(path);
+}
+function defaultLstatKind(path) {
+    try {
+        const st = lstatSync(path);
+        if (st.isSymbolicLink())
+            return "symlink";
+        if (st.isDirectory())
+            return "dir";
+        if (st.isFile())
+            return "file";
+        return "other";
+    }
+    catch {
+        return "missing";
+    }
+}
+function defaultReadDir(path) {
+    try {
+        return readdirSync(path);
+    }
+    catch {
+        return [];
+    }
+}
+function envTruthy(value) {
+    if (value === undefined)
+        return false;
+    const v = value.trim().toLowerCase();
+    if (v === "" || v === "0" || v === "false" || v === "no" || v === "off")
+        return false;
+    return true;
+}
+/**
+ * Resolve OpenClaw state directory: OPENCLAW_STATE_DIR or ~/.openclaw.
+ */
+export function resolveOpenClawStateDir(env = process.env, home = homedir()) {
+    const fromEnv = env.OPENCLAW_STATE_DIR?.trim();
+    if (fromEnv)
+        return resolve(fromEnv);
+    return resolve(home, ".openclaw");
+}
+/**
+ * Main agent workspace skills root under the state dir.
+ */
+export function resolveMainSkillsDir(stateDir) {
+    return join(stateDir, "workspace", "skills");
+}
+/**
+ * Detect OpenClaw from env signals and/or presence of the state directory.
+ */
+export function detectOpenClaw(env = process.env, options = {}) {
+    const home = options.homeDir ?? homedir();
+    const isDir = options.isDir ?? defaultIsDir;
+    const stateDir = resolveOpenClawStateDir(env, home);
+    const reasons = [];
+    if (envTruthy(env.OPENCLAW))
+        reasons.push("env:OPENCLAW");
+    if (envTruthy(env.DEFT_PROBE_OPENCLAW))
+        reasons.push("env:DEFT_PROBE_OPENCLAW");
+    if ((env.DEFT_AGENT_RUNTIME ?? "").trim().toLowerCase() === "openclaw") {
+        reasons.push("env:DEFT_AGENT_RUNTIME=openclaw");
+    }
+    if (env.OPENCLAW_STATE_DIR?.trim())
+        reasons.push("env:OPENCLAW_STATE_DIR");
+    if (isDir(stateDir))
+        reasons.push(`dir:${stateDir}`);
+    return {
+        detected: reasons.length > 0,
+        reasons,
+        stateDir,
+        mainSkillsDir: resolveMainSkillsDir(stateDir),
+    };
+}
+/**
+ * List in-scope skills directories. Default: main only.
+ * With allAgents: main + every workspace- star /skills under the state dir.
+ */
+export function listInScopeSkillsDirs(stateDir, allAgents, seams = {}) {
+    const isDir = seams.isDir ?? defaultIsDir;
+    const readDir = seams.readDir ?? defaultReadDir;
+    const main = resolveMainSkillsDir(stateDir);
+    const dirs = [main];
+    if (!allAgents)
+        return dirs;
+    for (const name of readDir(stateDir)) {
+        if (!name.startsWith("workspace-"))
+            continue;
+        const workspaceDir = join(stateDir, name);
+        if (!isDir(workspaceDir))
+            continue;
+        const skillsDir = join(workspaceDir, "skills");
+        if (!dirs.includes(skillsDir))
+            dirs.push(skillsDir);
+    }
+    return dirs;
+}
+/**
+ * Resolve content package skills/<id> for a pin.
+ */
+export function resolvePinSourceDir(contentBase, skillId) {
+    return join(contentBase, "skills", skillId);
+}
+function skillHasBody(skillDir, isFile, isDir) {
+    if (!isDir(skillDir) && !existsSync(skillDir))
+        return false;
+    // Accept dir or symlink-to-dir that contains SKILL.md
+    return isFile(join(skillDir, "SKILL.md"));
+}
+/**
+ * Assess which always-pins are present / missing / divergent in a skills root.
+ *
+ * - present: directory (or symlink) with SKILL.md
+ * - missing: path does not exist
+ * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ */
+export function assessOpenClawPins(skillsDir, seams = {}) {
+    const isDir = seams.isDir ?? defaultIsDir;
+    const isFile = seams.isFile ?? defaultIsFile;
+    const pathExists = seams.pathExists ?? defaultPathExists;
+    const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    const present = [];
+    const missing = [];
+    const divergent = [];
+    for (const skillId of OPENCLAW_ALWAYS_PIN_SKILLS) {
+        const target = join(skillsDir, skillId);
+        const kind = lstatKind(target);
+        if (kind === "missing") {
+            missing.push(skillId);
+            continue;
+        }
+        if (skillHasBody(target, isFile, isDir)) {
+            present.push(skillId);
+            continue;
+        }
+        // Path exists but is not a usable pin body (file, empty dir, broken link).
+        if (kind === "file" || kind === "other" || kind === "dir" || kind === "symlink") {
+            divergent.push(skillId);
+            continue;
+        }
+        if (!pathExists(target)) {
+            missing.push(skillId);
+            continue;
+        }
+        divergent.push(skillId);
+    }
+    return { skillsDir, present, missing, divergent };
+}
+function trySymlinkDir(target, path) {
+    try {
+        symlinkSync(target, path, "dir");
+        return true;
+    }
+    catch {
+        // Windows: junctions do not require elevated privileges for directories.
+        try {
+            symlinkSync(target, path, "junction");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function defaultCopyDir(src, dst) {
+    cpSync(src, dst, { recursive: true });
+}
+/**
+ * Install one pin into a skills root. Prefer symlink; copy on failure.
+ * Never deletes user skills. Divergent targets require force or TTY confirm.
+ */
+export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {}, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    const mkdirp = seams.mkdirp ?? ((p) => mkdirSync(p, { recursive: true }));
+    const symlinkDir = seams.symlinkDir ??
+        ((target, path) => {
+            if (!trySymlinkDir(target, path)) {
+                throw new Error(`symlink failed for ${path}`);
+            }
+        });
+    const copyDir = seams.copyDir ?? defaultCopyDir;
+    const removePath = seams.removePath ?? ((p) => rmSync(p, { recursive: true, force: true }));
+    const target = join(skillsDir, skillId);
+    const force = options.force === true || options.allowOverwrite === true;
+    if (!isDir(sourceDir) || !isFile(join(sourceDir, "SKILL.md"))) {
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: `source pin missing or incomplete: ${sourceDir}`,
+        };
+    }
+    mkdirp(skillsDir);
+    const kind = lstatKind(target);
+    if (kind !== "missing") {
+        if (skillHasBody(target, isFile, isDir)) {
+            return {
+                skillId,
+                method: "already-present",
+                target,
+                source: sourceDir,
+            };
+        }
+        if (!force) {
+            return {
+                skillId,
+                method: "skipped",
+                target,
+                source: sourceDir,
+                detail: "divergent target exists; re-run with --force or confirm on TTY to replace",
+            };
+        }
+        removePath(target);
+    }
+    try {
+        symlinkDir(sourceDir, target);
+        return { skillId, method: "symlink", target, source: sourceDir };
+    }
+    catch {
+        try {
+            copyDir(sourceDir, target);
+            return { skillId, method: "copy", target, source: sourceDir };
+        }
+        catch (err) {
+            return {
+                skillId,
+                method: "skipped",
+                target,
+                source: sourceDir,
+                detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+}
+/**
+ * Doctor check: detect OpenClaw + missing always-pins; optionally fix.
+ * No-ops when OpenClaw signals are absent.
+ */
+export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
+    const seams = options.seams ?? {};
+    const env = seams.env ?? process.env;
+    const homeDir = seams.homeDir ?? (() => homedir());
+    const isDir = seams.isDir ?? defaultIsDir;
+    const isFile = seams.isFile ?? defaultIsFile;
+    const detect = detectOpenClaw(env, { homeDir: homeDir(), isDir });
+    if (!detect.detected) {
+        sink.info(`${OPENCLAW_SKILL_PINS_CHECK}: skip -- OpenClaw not detected`);
+        addFinding({
+            severity: "skip",
+            message: "OpenClaw not detected",
+            check: OPENCLAW_SKILL_PINS_CHECK,
+            status: "skip",
+            reason: "openclaw-not-detected",
+        });
+        return;
+    }
+    const contentBase = (seams.contentRootFor ?? contentRoot)(options.frameworkRoot);
+    const skillsDirs = listInScopeSkillsDirs(detect.stateDir, options.allAgents, {
+        isDir,
+        readDir: seams.readDir,
+    });
+    const missingByDir = [];
+    const divergentByDir = [];
+    let allPresent = true;
+    for (const skillsDir of skillsDirs) {
+        const assessment = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+        if (assessment.missing.length > 0) {
+            allPresent = false;
+            missingByDir.push({ skillsDir, missing: [...assessment.missing] });
+        }
+        if (assessment.divergent.length > 0) {
+            allPresent = false;
+            divergentByDir.push({ skillsDir, divergent: [...assessment.divergent] });
+        }
+    }
+    if (allPresent) {
+        const scope = options.allAgents ? "main + workspace-* seats" : "main workspace";
+        const message = `${OPENCLAW_SKILL_PINS_CHECK}: OpenClaw host always-pins present ` +
+            `(${OPENCLAW_ALWAYS_PIN_SKILLS.join(", ")}) in ${scope}`;
+        sink.success(message);
+        addFinding({
+            severity: "skip",
+            message,
+            check: OPENCLAW_SKILL_PINS_CHECK,
+            status: "present",
+            skills_dirs: skillsDirs,
+            pins: [...OPENCLAW_ALWAYS_PIN_SKILLS],
+            detect_reasons: detect.reasons,
+        });
+        return;
+    }
+    // Optional fix path
+    const installResults = [];
+    if (options.fixMode) {
+        const isTty = seams.isTty ?? (() => process.stdin.isTTY === true);
+        const readYn = seams.readYn ?? (() => false);
+        let allowFix = true;
+        if (!options.jsonMode && isTty()) {
+            allowFix = readYn(`Wire missing OpenClaw always-pin skills into ${skillsDirs.join(", ")} now?`, true);
+            if (!allowFix) {
+                sink.info("Skipped OpenClaw pin wire -- re-run `deft doctor --fix` when ready.");
+            }
+        }
+        // Non-interactive --fix applies additive installs (safe); divergent needs --force.
+        if (allowFix) {
+            for (const skillsDir of skillsDirs) {
+                const assessment = assessOpenClawPins(skillsDir, {
+                    isDir,
+                    isFile,
+                    lstatKind: seams.lstatKind,
+                });
+                const toInstall = new Set([
+                    ...assessment.missing,
+                    ...(options.force ? assessment.divergent : []),
+                ]);
+                if (!options.force && assessment.divergent.length > 0 && isTty() && !options.jsonMode) {
+                    for (const skillId of assessment.divergent) {
+                        if (readYn(`Replace divergent OpenClaw skill dir ${join(skillsDir, skillId)} with pin from content package?`, false)) {
+                            toInstall.add(skillId);
+                        }
+                    }
+                }
+                for (const skillId of toInstall) {
+                    const sourceDir = resolvePinSourceDir(contentBase, skillId);
+                    const result = installOpenClawPin(skillId, sourceDir, skillsDir, { force: options.force || assessment.divergent.includes(skillId) }, seams);
+                    installResults.push(result);
+                    if (result.method === "symlink" || result.method === "copy") {
+                        sink.success(`OpenClaw pin ${skillId}: ${result.method} → ${result.target}${result.method === "symlink" ? ` (from ${result.source})` : ""}`);
+                    }
+                    else if (result.method === "already-present") {
+                        sink.info(`OpenClaw pin ${skillId}: already present at ${result.target}`);
+                    }
+                    else {
+                        sink.warn(`OpenClaw pin ${skillId}: skipped${result.detail ? ` -- ${result.detail}` : ""}`);
+                    }
+                }
+            }
+        }
+        // Re-assess after fix
+        let stillMissing = false;
+        const postMissing = [];
+        for (const skillsDir of skillsDirs) {
+            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+            if (post.missing.length > 0 || post.divergent.length > 0) {
+                stillMissing = true;
+                postMissing.push(...post.missing.map((id) => `${skillsDir}/${id}`), ...post.divergent.map((id) => `${skillsDir}/${id} (divergent)`));
+            }
+        }
+        if (!stillMissing) {
+            const message = `${OPENCLAW_SKILL_PINS_CHECK}: wired OpenClaw always-pins; ` +
+                "restart the OpenClaw gateway or start a new session so available_skills refreshes";
+            sink.success(message);
+            addFinding({
+                severity: "skip",
+                message,
+                check: OPENCLAW_SKILL_PINS_CHECK,
+                status: "fixed",
+                skills_dirs: skillsDirs,
+                installs: installResults,
+                detect_reasons: detect.reasons,
+            });
+            return;
+        }
+        // Fall through to warning with remaining gaps
+        missingByDir.length = 0;
+        divergentByDir.length = 0;
+        for (const skillsDir of skillsDirs) {
+            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+            if (post.missing.length > 0)
+                missingByDir.push({ skillsDir, missing: [...post.missing] });
+            if (post.divergent.length > 0)
+                divergentByDir.push({ skillsDir, divergent: [...post.divergent] });
+        }
+    }
+    const missingIds = [...new Set(missingByDir.flatMap((m) => m.missing))];
+    const divergentIds = [...new Set(divergentByDir.flatMap((d) => d.divergent))];
+    const targetSummary = skillsDirs.join(", ");
+    const sourceHint = join(contentBase, "skills", "<pin-id>");
+    const multiHint = options.allAgents ? "" : ` Multi-seat workspaces: ${REMEDIATION_ALL_AGENTS}.`;
+    const message = `${OPENCLAW_SKILL_PINS_CHECK}: missing OpenClaw always-pin skill(s) ` +
+        `[${missingIds.join(", ") || "(none)"}]` +
+        (divergentIds.length > 0 ? `; divergent: [${divergentIds.join(", ")}]` : "") +
+        ` under ${targetSummary}. ` +
+        `Source: ${sourceHint}. ` +
+        `Remediation: ${REMEDIATION_FIX}. ` +
+        `See ${DOC_OPENCLAW_HOST}, ${DOC_HOST_LIFECYCLE}, ${DOC_SKILL_PINS}.` +
+        multiHint;
+    sink.warn(message);
+    if (!options.jsonMode) {
+        sink.info("After wiring pins, restart the OpenClaw gateway or open a new session so host available_skills refreshes.");
+    }
+    addFinding({
+        severity: "warning",
+        message,
+        check: OPENCLAW_SKILL_PINS_CHECK,
+        status: "missing",
+        missing: missingIds,
+        divergent: divergentIds,
+        skills_dirs: skillsDirs,
+        main_skills_dir: detect.mainSkillsDir,
+        source_content_root: contentBase,
+        suggestion: REMEDIATION_FIX,
+        docs: [DOC_OPENCLAW_HOST, DOC_HOST_LIFECYCLE, DOC_SKILL_PINS],
+        detect_reasons: detect.reasons,
+        ...(installResults.length > 0 ? { installs: installResults } : {}),
+    });
+}
+//# sourceMappingURL=openclaw-skills.js.map

package/dist/doctor/types.d.ts

@@ -75,6 +75,10 @@ export interface DoctorFlags {
     readonly network: boolean;
     readonly help: boolean;
     readonly projectRoot: string | null;
+    /** Replace divergent OpenClaw pin dirs during doctor --fix (#3001). */
+    readonly force: boolean;
+    /** Wire always-pins into main + every workspace-* seat (#3001). */
+    readonly openclawAllAgents: boolean;
     readonly unknown: readonly string[];
 }
 export interface ThrottleDecision {
@@ -150,5 +154,23 @@ export interface DoctorSeams {
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
     /** Live hook spawn probe for doctor --full (#2852). */
     readonly probeAgentHooksLive?: (projectRoot: string) => AgentHookLiveProbeResult;
+    /**
+     * xBRIEF project-envelope staleness probe (#2971). Injected so doctor can
+     * fail closed on 0.6 project JSON under an xbrief/ layout without re-deriving
+     * the shared `probeXbriefStaleness` path in tests.
+     */
+    readonly probeXbriefEnvelope?: (projectRoot: string) => {
+        readonly declaredVersion: string | null;
+        readonly targetVersion: string;
+        readonly distance: "current" | "behind-minor" | "behind-major";
+        readonly stale: boolean;
+    };
+    /**
+     * OpenClaw skill-pin seams (#3001). Injected so detect/fix stays offline +
+     * deterministic in tests (fake HOME / env / fs).
+     */
+    readonly openclawEnv?: NodeJS.ProcessEnv;
+    readonly openclawHomeDir?: () => string;
+    readonly openclawContentRootFor?: (frameworkRoot: string) => string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/escalation/actions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Operator-facing escalation actions: file, list, resolve, batch-approve (#518).
+ */
+import { type EscalationEvent, type EscalationType } from "./types.js";
+export interface FileEscalationInput {
+    readonly projectRoot: string;
+    readonly type: string;
+    readonly title: string;
+    readonly body?: string;
+    readonly agentId?: string;
+    readonly contextRefs?: readonly string[];
+    readonly slaHours?: number;
+    readonly dangerous?: boolean;
+    readonly id?: string;
+    readonly now?: Date;
+}
+export declare function fileEscalation(input: FileEscalationInput): EscalationEvent;
+export interface ResolveEscalationInput {
+    readonly projectRoot: string;
+    readonly id: string;
+    readonly decision: string;
+    readonly actor?: string;
+    readonly note?: string | null;
+    readonly answer?: string | null;
+    readonly now?: Date;
+}
+export type ResolveEscalationResult = {
+    readonly ok: true;
+    readonly event: EscalationEvent;
+} | {
+    readonly ok: false;
+    readonly code: "not-found" | "already-resolved" | "invalid-decision";
+    readonly message: string;
+};
+export declare function resolveEscalation(input: ResolveEscalationInput): ResolveEscalationResult;
+export interface BatchApproveInput {
+    readonly projectRoot: string;
+    /** Limit to these ids; empty/undefined = all open batch-eligible. */
+    readonly ids?: readonly string[];
+    readonly actor?: string;
+    readonly note?: string | null;
+    /** When false (default), skip `dangerous: true` items. */
+    readonly includeDangerous?: boolean;
+    readonly now?: Date;
+}
+export interface BatchApproveResult {
+    readonly approved: EscalationEvent[];
+    readonly skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Bulk-approve only `cmd_approval` and `question` open items.
+ * design_decision / approval / resource / external must use individual resolve.
+ * Dangerous items are skipped unless `includeDangerous` is true.
+ */
+export declare function batchApproveEscalations(input: BatchApproveInput): BatchApproveResult;
+export declare function listEscalationsFiltered(projectRoot: string, opts?: {
+    openOnly?: boolean;
+    type?: EscalationType;
+}): EscalationEvent[];
+//# sourceMappingURL=actions.d.ts.map