@deftai/directive-core 0.96.0 → 0.98.0

package/dist/session/compact-ritual.js

@@ -0,0 +1,237 @@
+/**
+ * Soft post-compact / post-amnesia AGENTS re-bind (#3171 / epic #2769 pass-3).
+ *
+ * Single in-repo source of truth for the soft checklist. File-host compact and
+ * SessionStart hooks, Codex best-effort SessionStart, and the OpenClaw durable
+ * skill adapter all derive from this module — no divergent host-only rule text.
+ *
+ * Soft complements hard Tier-1 compact re-arm (#2113). Soft never replaces,
+ * weakens, or short-circuits PreToolUse deny / mutation ritual.
+ */
+/** Epic + implement child anchors for docs and wire markers. */
+export const SOFT_AGENTS_REBIND_EPIC = 2769;
+export const SOFT_AGENTS_REBIND_ISSUE = 3171;
+export const SOFT_AGENTS_REBIND_EVIDENCE_ISSUE = 3161;
+/** Stable marker substring present in every host-facing soft deposit. */
+export const SOFT_AGENTS_REBIND_MARKER = "Directive soft post-compact AGENTS re-bind (#3171 / #2769)";
+/** Managed OpenClaw skill directory name (doctor/init deposit). */
+export const OPENCLAW_SOFT_REBIND_SKILL_ID = "deft-directive-post-compact-rebind";
+/** Sentinel inside managed OpenClaw skill bodies for rewrite detection. */
+export const OPENCLAW_SOFT_REBIND_MANAGED_MARKER = "<!-- deft:managed soft-agents-rebind #3171 -->";
+/**
+ * Pass-3 §2 checklist obligations — one ordered list, all hosts consume.
+ * Host adapters may wrap packaging; they must not invent alternate rule text.
+ */
+export const SOFT_AGENTS_REBIND_CHECKLIST = [
+    {
+        id: "reread-agents",
+        text: "Re-read managed AGENTS.md session routing (#2176). Do not treat the " +
+            "compaction summary or host runbook as SoT.",
+    },
+    {
+        id: "confirm-learned",
+        text: "Confirm-what-you-learned in the user-visible reply (brief): alignment " +
+            "posture; addressing-name when USER.md applies; product SoT is not the " +
+            "compaction/summary.",
+    },
+    {
+        id: "deposit-integrity",
+        text: "Deposit integrity: if .deft/core/main.md (or managed deposit) is missing " +
+            "or broken while deft may still be on PATH, fail closed to doctor / " +
+            "QUICK-START before product shell. (deft on PATH ≠ healthy deposit.)",
+    },
+    {
+        id: "summary-not-sot",
+        text: "Summary ≠ SoT: compaction/session runbooks (demo DBs, demo apps, ports, " +
+            '"start the frontend") are hypotheses. Re-verify against PROJECT-DEFINITION ' +
+            "/ USER.md / real local config before starting services or inventing demo " +
+            "stacks. (#3161 G)",
+    },
+    {
+        id: "operational-ask-trap",
+        text: 'Operational-ask trap: "open / start / run the app", "bring it up locally", ' +
+            '"open the browser" are still session-routed. They are not an escape hatch ' +
+            "from AGENTS.md, USER.md, or PROJECT-DEFINITION. (#3161 F)",
+    },
+    {
+        id: "mutation-vs-readonly",
+        text: "Mutation vs read-only: read-only / advisory / pure orientation → soft " +
+            "checklist only (do not force full cold session:start). Mutation intent " +
+            "(writes, implement, start-of-story) → soft checklist plus hard re-arm " +
+            "where the host supports it (session:ready / session:start --rearm or cold) " +
+            "before gated tools. Soft never authorizes skipping the mutation ritual for writes.",
+    },
+];
+/**
+ * Five-row host matrix (Cursor / Claude / Grok / Codex / OpenClaw).
+ * Docs and deposit tests must stay aligned with this table.
+ */
+export const SOFT_REBIND_HOST_MATRIX = [
+    {
+        host: "cursor",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "session.compact (preCompact) + session.start additional_context",
+    },
+    {
+        host: "claude",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "PreCompact/PostCompact + SessionStart additionalContext",
+    },
+    {
+        host: "grok",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "PreCompact/PostCompact + SessionStart soft cue (#3161 dogfood host)",
+    },
+    {
+        host: "codex",
+        family: "file-host (limited)",
+        hardCompact: "unsupported",
+        softRebind: "docs-best-effort",
+        wire: "SessionStart soft cue only — no native compact hook",
+    },
+    {
+        host: "openclaw",
+        family: "Family-2 session host",
+        hardCompact: "unsupported",
+        softRebind: "required",
+        wire: "durable workspace skill via doctor/init; not file-host hooks alone",
+    },
+];
+/** Forbidden soft wording — soft must never invite skipping mutation ritual. */
+export const SOFT_REBIND_FORBIDDEN_PHRASES = [
+    "skip session:start for writes",
+    "skip the mutation ritual",
+    "you may skip session:start",
+    "ritual not required for writes",
+    "soft replaces hard",
+];
+/**
+ * Format the shared soft checklist for host injection / skill bodies.
+ */
+export function formatSoftAgentsRebindChecklist(options = {}) {
+    const includeHeader = options.includeHeader !== false;
+    const lines = [];
+    if (includeHeader) {
+        lines.push(SOFT_AGENTS_REBIND_MARKER);
+        lines.push("After compaction, resume, or long-session amnesia: restore AGENTS rule " +
+            "memory before product action. Soft complements hard compact re-arm; " +
+            "it does not complete or replace the gated mutation ritual.");
+        lines.push("");
+    }
+    lines.push("Soft AGENTS re-bind checklist:");
+    SOFT_AGENTS_REBIND_CHECKLIST.forEach((item, index) => {
+        lines.push(`${index + 1}. ${item.text}`);
+    });
+    return lines.join("\n");
+}
+/**
+ * Append soft checklist to a hard compact re-arm (or SessionStart) message.
+ * Hard text stays first so existing recoveries remain discoverable.
+ */
+export function appendSoftAgentsRebindToMessage(hardMessage) {
+    const hard = hardMessage.trim();
+    const soft = formatSoftAgentsRebindChecklist();
+    if (hard.length === 0)
+        return soft;
+    if (hard.includes(SOFT_AGENTS_REBIND_MARKER))
+        return hard;
+    return `${hard}\n\n${soft}`;
+}
+/** True when text carries the soft re-bind deposit (tests + doctor). */
+export function isSoftAgentsRebindText(text) {
+    return text.includes(SOFT_AGENTS_REBIND_MARKER);
+}
+/** Soft cue events that should inject checklist without requiring a write tool. */
+export function isSoftAgentsRebindEvent(event) {
+    return event === "session.start" || event === "session.compact";
+}
+/**
+ * Whether this decision should carry soft injection on the host wire.
+ * Disabled / opt-out codes stay hard-message only.
+ */
+export function decisionCarriesSoftAgentsRebind(input) {
+    if (!isSoftAgentsRebindEvent(input.event))
+        return false;
+    if (input.code === "session-start-disabled")
+        return false;
+    if (input.code === "directive-disabled")
+        return false;
+    return (input.code === "session-start" ||
+        input.code === "session-start-degraded" ||
+        input.code === "session-compact-rearm" ||
+        input.code === "session-compact-rearm-degraded" ||
+        input.code === "session-compact-noop");
+}
+/**
+ * Managed OpenClaw skill body generated from the same SoT checklist.
+ * Skill-shaped packaging; obligations identical to file-host soft text.
+ */
+export function formatOpenClawSoftRebindSkillMarkdown() {
+    const checklist = formatSoftAgentsRebindChecklist({ includeHeader: false });
+    return [
+        "---",
+        `name: ${OPENCLAW_SOFT_REBIND_SKILL_ID}`,
+        "description: >-",
+        "  Soft post-compact / post-amnesia AGENTS re-bind for OpenClaw (#3171 / #2769).",
+        "  Load after session start, gateway restart, or long-session amnesia.",
+        "  Complements hard file-host compact re-arm; does not replace mutation ritual.",
+        "---",
+        OPENCLAW_SOFT_REBIND_MANAGED_MARKER,
+        "",
+        "# Soft post-compact AGENTS re-bind (OpenClaw)",
+        "",
+        SOFT_AGENTS_REBIND_MARKER,
+        "",
+        "OpenClaw is a **Family-2** session host. It does **not** claim file-host",
+        "`PreCompact` / `PreToolUse` hard compact re-arm alone. This skill is the",
+        "**required** durable soft surface: same checklist obligations as Cursor,",
+        "Claude Code, and Grok Build.",
+        "",
+        "## When to load",
+        "",
+        "- Session start / resume after amnesia boundary",
+        "- Gateway restart or new OpenClaw session context",
+        "- Long-running session where AGENTS.md session routing may have dropped",
+        "- Operational asks after summary resume (start/open app, demo stack)",
+        "",
+        "## Checklist (shared SoT — do not invent host-only rules)",
+        "",
+        checklist,
+        "",
+        "## Hard path honesty",
+        "",
+        "- Soft **never** authorizes skipping `session:start` / `session:ready` /",
+        "  gated ritual for mutation (writes, implement, story start).",
+        "- Where OpenClaw lacks file-host compact PreToolUse, operators still run",
+        "  the mutation ritual via skills / CLI before gated writes.",
+        "- Pins present ≠ session ritual completed.",
+        "",
+        "## Operator recovery",
+        "",
+        "- Deposit / refresh: `deft doctor --fix` (OpenClaw detected) or",
+        "  `deft update` / `directive init` when OpenClaw signals are present.",
+        "- After deposit: restart the OpenClaw gateway or start a new session so",
+        "  skills reload.",
+        "- Docs: `docs/openclaw-agent-host.md` § Soft post-compact AGENTS re-bind.",
+        "",
+    ].join("\n");
+}
+/** True when skill body is the managed #3171 soft re-bind deposit. */
+export function isManagedOpenClawSoftRebindSkill(body) {
+    return body.includes(OPENCLAW_SOFT_REBIND_MANAGED_MARKER);
+}
+/**
+ * Assert soft text never invites skipping mutation ritual (unit + deposit tests).
+ * Returns empty array when clean.
+ */
+export function softAgentsRebindForbiddenHits(text) {
+    const lower = text.toLowerCase();
+    return SOFT_REBIND_FORBIDDEN_PHRASES.filter((phrase) => lower.includes(phrase.toLowerCase()));
+}
+//# sourceMappingURL=compact-ritual.js.map

package/dist/session/compact-ritual.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compact-ritual.spec.d.ts.map

package/dist/session/compact-ritual.spec.js

@@ -0,0 +1,21 @@
+/**
+ * Forward-coverage companion for new compact-ritual.ts (#3171 / #1310).
+ * Hard-path #2113 cases live in compact-ritual.test.ts (pre-existing).
+ */
+import { describe, expect, it } from "vitest";
+import { formatSoftAgentsRebindChecklist, isSoftAgentsRebindText, SOFT_AGENTS_REBIND_CHECKLIST, SOFT_AGENTS_REBIND_MARKER, SOFT_REBIND_HOST_MATRIX, softAgentsRebindForbiddenHits, } from "./compact-ritual.js";
+describe("compact-ritual soft SoT forward coverage (#3171)", () => {
+    it("exports a six-item shared checklist SoT", () => {
+        expect(SOFT_AGENTS_REBIND_CHECKLIST).toHaveLength(6);
+        const text = formatSoftAgentsRebindChecklist();
+        expect(isSoftAgentsRebindText(text)).toBe(true);
+        expect(text).toContain(SOFT_AGENTS_REBIND_MARKER);
+        expect(softAgentsRebindForbiddenHits(text)).toEqual([]);
+    });
+    it("lists five hosts with Codex gap and OpenClaw required soft", () => {
+        expect(SOFT_REBIND_HOST_MATRIX).toHaveLength(5);
+        expect(SOFT_REBIND_HOST_MATRIX.find((r) => r.host === "codex")?.softRebind).toBe("docs-best-effort");
+        expect(SOFT_REBIND_HOST_MATRIX.find((r) => r.host === "openclaw")?.softRebind).toBe("required");
+    });
+});
+//# sourceMappingURL=compact-ritual.spec.js.map

package/dist/session/coverage-check-resume-nudge.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session-start skippable nudge for coverageDebt + checkResume (#3189).
+ *
+ * Why / what + Strict / Hatch-aware / Later (+ Discuss / Back for #1470).
+ * Later does not mark decided; re-nag next interactive mutation ritual.
+ * Headless / CI / non-TTY fail-open (no block).
+ */
+import { type HeadlessDetectionOptions } from "../product-signal/headless.js";
+/** Why block -- must appear in the nudge. */
+export declare const COVERAGE_CHECK_RESUME_NUDGE_WHY: string;
+/** What block -- bundled presets, not five micro-toggles. */
+export declare const COVERAGE_CHECK_RESUME_NUDGE_WHAT: string;
+export declare const COVERAGE_CHECK_RESUME_NUDGE_BODY: string;
+export interface CoverageCheckResumeNudgeEligibilityOptions extends HeadlessDetectionOptions {
+    readonly projectRoot: string;
+}
+/**
+ * True when an interactive mutation session-start ritual should surface the
+ * coverage/check-resume decision nudge (#3189).
+ */
+export declare function isCoverageCheckResumeNudgeEligible(options: CoverageCheckResumeNudgeEligibilityOptions): boolean;
+/** Format the full operator-facing nudge. */
+export declare function formatCoverageCheckResumeNudge(): string;
+/**
+ * Emit the nudge when eligible; headless / decided callers get an empty string.
+ * Never blocks -- session-start always continues.
+ *
+ * Design note (#3189): session-start is non-interactive for agent hosts (same
+ * class as product-signal D17). Choice dispatch is via CLI verbs named in the
+ * nudge body (`policy:coverage-check-resume-preset|later|dismiss`), not a
+ * blocking TTY menu inside session:start.
+ */
+export declare function maybeFormatCoverageCheckResumeNudge(options: CoverageCheckResumeNudgeEligibilityOptions): string;
+//# sourceMappingURL=coverage-check-resume-nudge.d.ts.map

package/dist/session/coverage-check-resume-nudge.js

@@ -0,0 +1,66 @@
+/**
+ * Session-start skippable nudge for coverageDebt + checkResume (#3189).
+ *
+ * Why / what + Strict / Hatch-aware / Later (+ Discuss / Back for #1470).
+ * Later does not mark decided; re-nag next interactive mutation ritual.
+ * Headless / CI / non-TTY fail-open (no block).
+ */
+import { isCoverageCheckResumeUndecided } from "../policy/coverage-check-resume-presets.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
+import { isHeadlessSession } from "../product-signal/headless.js";
+/** Why block -- must appear in the nudge. */
+export const COVERAGE_CHECK_RESUME_NUDGE_WHY = "Why: Long checks often fail late on small gates, or barely miss coverage. " +
+    "The project can fail closed, warn, or hatch with a tracked debt issue on THIS repo. " +
+    "Local machines may resume a suite that already passed at the same commit; " +
+    "CI must not trust a laptop stamp.";
+/** What block -- bundled presets, not five micro-toggles. */
+export const COVERAGE_CHECK_RESUME_NUDGE_WHAT = "What we need: one bundled project decision (not USER.md personal prefs; not npm publish; " +
+    "not turning off required CI):\n" +
+    "  * Strict (recommended for most apps) -- coverageDebt.mode=off, checkResume.localStamp=off\n" +
+    "  * Hatch-aware -- coverageDebt.mode=hatch (autoFile=false by default), localStamp=on for DX\n" +
+    "  * Later -- skip this session; does NOT set status=decided; nag again next ritual\n" +
+    "  * Discuss -- talk through the trade-offs\n" +
+    "  * Back -- leave this prompt without choosing\n" +
+    "Apply path (writes PROJECT-DEFINITION):\n" +
+    "  Strict -> `" +
+    policyColonInvocation("coverage-check-resume-preset", " -- --preset strict") +
+    "`\n" +
+    "  Hatch-aware -> `" +
+    policyColonInvocation("coverage-check-resume-preset", " -- --preset hatch-aware") +
+    "`\n" +
+    "  Later -> `" +
+    policyColonInvocation("coverage-check-resume-later") +
+    "` (no PD write)\n" +
+    "  Dismiss-with-reason -> `" +
+    policyColonInvocation("coverage-check-resume-dismiss", ' -- --reason "…"') +
+    "`\n" +
+    "Stop nag only after Strict / Hatch-aware (status=decided) or dismiss-with-reason " +
+    `(visible via \`${policyColonInvocation("show", " --field=coverageDebt")}\` / doctor).`;
+export const COVERAGE_CHECK_RESUME_NUDGE_BODY = `${COVERAGE_CHECK_RESUME_NUDGE_WHY}\n\n${COVERAGE_CHECK_RESUME_NUDGE_WHAT}`;
+/**
+ * True when an interactive mutation session-start ritual should surface the
+ * coverage/check-resume decision nudge (#3189).
+ */
+export function isCoverageCheckResumeNudgeEligible(options) {
+    if (isHeadlessSession(options)) {
+        return false;
+    }
+    return isCoverageCheckResumeUndecided(options.projectRoot);
+}
+/** Format the full operator-facing nudge. */
+export function formatCoverageCheckResumeNudge() {
+    return `[deft policy] coverageDebt + checkResume undecided:\n${COVERAGE_CHECK_RESUME_NUDGE_BODY}\n`;
+}
+/**
+ * Emit the nudge when eligible; headless / decided callers get an empty string.
+ * Never blocks -- session-start always continues.
+ *
+ * Design note (#3189): session-start is non-interactive for agent hosts (same
+ * class as product-signal D17). Choice dispatch is via CLI verbs named in the
+ * nudge body (`policy:coverage-check-resume-preset|later|dismiss`), not a
+ * blocking TTY menu inside session:start.
+ */
+export function maybeFormatCoverageCheckResumeNudge(options) {
+    return isCoverageCheckResumeNudgeEligible(options) ? formatCoverageCheckResumeNudge() : "";
+}
+//# sourceMappingURL=coverage-check-resume-nudge.js.map

package/dist/session/index.d.ts

@@ -1,5 +1,8 @@
+export * from "./compact-ritual.js";
+export * from "./coverage-check-resume-nudge.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";

package/dist/session/index.js

@@ -1,5 +1,8 @@
+export * from "./compact-ritual.js";
+export * from "./coverage-check-resume-nudge.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";

package/dist/session/openclaw-soft-rebind-deposit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OpenClaw durable soft AGENTS re-bind skill deposit (#3171 / #2769).
+ *
+ * Deposits a managed workspace skill generated from the shared checklist SoT
+ * in compact-ritual.ts. Fail-closed when OpenClaw is not detected (unless
+ * forceDeposit for tests). Real directory copy — not symlink-escape into npm.
+ */
+import { type OpenClawDetectResult } from "../doctor/openclaw-skills.js";
+export interface OpenClawSoftRebindDepositResult {
+    readonly changed: boolean;
+    readonly writtenPaths: string[];
+    readonly preservedCustomPaths: string[];
+    readonly skillsDirs: string[];
+    readonly skipped: boolean;
+    readonly skipReason?: string;
+    readonly detect: OpenClawDetectResult | null;
+    readonly present: boolean;
+}
+export interface OpenClawSoftRebindDepositOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDir?: string;
+    readonly allAgents?: boolean;
+    readonly forceDeposit?: boolean;
+    readonly skillsDirs?: readonly string[];
+    readonly isDir?: (path: string) => boolean;
+    readonly readDir?: (path: string) => string[];
+}
+/**
+ * Assess whether the managed soft re-bind skill is present and current.
+ *
+ * Unmanaged/custom content at the required slug is NOT present (#3171 P1 /
+ * Greptile): the soft checklist obligations are the health criterion, not
+ * merely occupying the skill directory name.
+ */
+export declare function assessOpenClawSoftRebindSkill(skillsDir: string, options?: {
+    readonly expectedBody?: string;
+}): {
+    readonly present: boolean;
+    readonly custom: boolean;
+    readonly path: string;
+};
+/**
+ * Deposit the managed OpenClaw soft re-bind skill into workspace skills roots.
+ */
+export declare function depositOpenClawSoftRebindSkill(options?: OpenClawSoftRebindDepositOptions): OpenClawSoftRebindDepositResult;
+//# sourceMappingURL=openclaw-soft-rebind-deposit.d.ts.map

package/dist/session/openclaw-soft-rebind-deposit.js

@@ -0,0 +1,165 @@
+/**
+ * OpenClaw durable soft AGENTS re-bind skill deposit (#3171 / #2769).
+ *
+ * Deposits a managed workspace skill generated from the shared checklist SoT
+ * in compact-ritual.ts. Fail-closed when OpenClaw is not detected (unless
+ * forceDeposit for tests). Real directory copy — not symlink-escape into npm.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { detectOpenClaw, isEscapingSkillSymlink, listInScopeSkillsDirs, } from "../doctor/openclaw-skills.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { formatOpenClawSoftRebindSkillMarkdown, isManagedOpenClawSoftRebindSkill, OPENCLAW_SOFT_REBIND_SKILL_ID, } from "./compact-ritual.js";
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+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";
+    }
+}
+/**
+ * Assess whether the managed soft re-bind skill is present and current.
+ *
+ * Unmanaged/custom content at the required slug is NOT present (#3171 P1 /
+ * Greptile): the soft checklist obligations are the health criterion, not
+ * merely occupying the skill directory name.
+ */
+export function assessOpenClawSoftRebindSkill(skillsDir, options = {}) {
+    const path = join(skillsDir, OPENCLAW_SOFT_REBIND_SKILL_ID, "SKILL.md");
+    if (!existsSync(path)) {
+        return { present: false, custom: false, path };
+    }
+    let body;
+    try {
+        body = readFileSync(path, "utf8");
+    }
+    catch {
+        return { present: false, custom: false, path };
+    }
+    if (!isManagedOpenClawSoftRebindSkill(body)) {
+        // Occupying the slug with unrelated content fails health (#3171 Greptile P1).
+        return { present: false, custom: true, path };
+    }
+    const expected = options.expectedBody ?? formatOpenClawSoftRebindSkillMarkdown();
+    return { present: body === expected, custom: false, path };
+}
+/**
+ * Deposit the managed OpenClaw soft re-bind skill into workspace skills roots.
+ */
+export function depositOpenClawSoftRebindSkill(options = {}) {
+    const env = options.env ?? process.env;
+    const home = options.homeDir ?? homedir();
+    const isDir = options.isDir ?? defaultIsDir;
+    const detect = detectOpenClaw(env, { homeDir: home, isDir });
+    if (!detect.detected && !options.forceDeposit) {
+        return {
+            changed: false,
+            writtenPaths: [],
+            preservedCustomPaths: [],
+            skillsDirs: [],
+            skipped: true,
+            skipReason: "openclaw-not-detected",
+            detect,
+            present: false,
+        };
+    }
+    const skillsDirs = options.skillsDirs !== undefined
+        ? [...options.skillsDirs]
+        : listInScopeSkillsDirs(detect.stateDir, options.allAgents === true, {
+            isDir,
+            readDir: options.readDir,
+        });
+    const expected = formatOpenClawSoftRebindSkillMarkdown();
+    const writtenPaths = [];
+    const preservedCustomPaths = [];
+    let changed = false;
+    let presentCount = 0;
+    for (const skillsDir of skillsDirs) {
+        const skillDir = join(skillsDir, OPENCLAW_SOFT_REBIND_SKILL_ID);
+        const skillFile = join(skillDir, "SKILL.md");
+        const kind = defaultLstatKind(skillDir);
+        if (kind === "symlink" && isEscapingSkillSymlink(skillsDir, skillDir)) {
+            // Replace unusable escaping symlink with a real copy.
+            try {
+                rmSync(skillDir, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort
+            }
+        }
+        if (existsSync(skillFile)) {
+            let existing = "";
+            try {
+                existing = readFileSync(skillFile, "utf8");
+            }
+            catch {
+                existing = "";
+            }
+            // Required soft re-bind surface: unmanaged content at this slug is a gap,
+            // not a preserve-as-present path (Greptile P1 on #3171). Overwrite with
+            // the managed checklist so doctor/init/update cannot report success while
+            // the operational-ask obligations are absent.
+            if (existing === expected) {
+                presentCount += 1;
+                continue;
+            }
+        }
+        mkdirSync(skillDir, { recursive: true });
+        const tmpName = `SKILL.md.deft-${process.pid}-${Date.now().toString(36)}.tmp`;
+        const staging = join(skillDir, tmpName);
+        try {
+            // Contained write under skills root (#2951) — refuses symlink escape.
+            containedWrite({
+                root: skillsDir,
+                target: staging,
+                data: expected,
+                mode: "replace",
+            });
+            renameSync(staging, skillFile);
+        }
+        catch (err) {
+            try {
+                rmSync(staging, { force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/contained write refused|symlink|escape/i.test(msg)) {
+                preservedCustomPaths.push(skillFile);
+                continue;
+            }
+            throw err;
+        }
+        writtenPaths.push(skillFile);
+        changed = true;
+        presentCount += 1;
+    }
+    return {
+        changed,
+        writtenPaths,
+        preservedCustomPaths,
+        skillsDirs,
+        skipped: false,
+        detect,
+        present: presentCount === skillsDirs.length && skillsDirs.length > 0,
+    };
+}
+//# sourceMappingURL=openclaw-soft-rebind-deposit.js.map

package/dist/session/session-start.js

@@ -18,6 +18,7 @@ import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
+import { maybeFormatCoverageCheckResumeNudge } from "./coverage-check-resume-nudge.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
 import { emitSessionStartProcessCost } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
@@ -433,6 +434,16 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     if (humanMergeLine !== null) {
         lines.push(humanMergeLine);
     }
+    // #3189: re-arm still surfaces undecided coverage/check-resume once per ritual.
+    try {
+        const coverageNudge = maybeFormatCoverageCheckResumeNudge({ projectRoot });
+        if (coverageNudge.length > 0) {
+            lines.push(coverageNudge.trimEnd());
+        }
+    }
+    catch {
+        // best-effort — re-arm must not abort
+    }
     const priorQuick = eligibility.state.quickSteps;
     const priorTriage = priorQuick.triage_welcome ?? ritualStep({ ok: true, ts: instant });
     const policyOk = policyResult.error === null || policyResult.source === "default-fail-closed";
@@ -863,6 +874,16 @@ export function runSessionStart(projectRoot, options = {}) {
     if (consentPrompt.length > 0) {
         lines.push(consentPrompt.trimEnd());
     }
+    // #3189: skippable coverageDebt/checkResume project-decision nudge (fail-open; never blocks).
+    try {
+        const coverageNudge = maybeFormatCoverageCheckResumeNudge({ projectRoot });
+        if (coverageNudge.length > 0) {
+            lines.push(coverageNudge.trimEnd());
+        }
+    }
+    catch {
+        // best-effort operator advisory — session start must not abort
+    }
     const writeStarted = performance.now();
     const coldSessionId = (options.newSessionId ?? randomUUID)();
     const payload = newRitualStatePayload({