@deftai/directive-core 0.107.0 → 0.108.0

package/dist/hooks/classify/host-session-identity.js

@@ -0,0 +1,470 @@
+/**
+ * Cooperative host-session identity and exact lifecycle-command rewriting (#3611).
+ *
+ * This is payload classification, not authentication. Host hook JSON is locally
+ * forgeable under the occupancy model's cooperating-process assumption.
+ */
+import { isShellTool } from "../tools.js";
+import { record, toolInputRecord } from "./payload.js";
+import { hookToolName } from "./tool-name.js";
+export const HOST_IDENTITY_PROVIDERS = ["codex", "claude", "cursor"];
+export const MAX_HOOK_HOST_IDENTITY_UTF8_BYTES = 512;
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit <= 0x1f || (unit >= 0x7f && unit <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function hasUnpairedUtf16Surrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+            continue;
+        }
+        if (unit >= 0xdc00 && unit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+function identityField(input, fieldName) {
+    if (!(fieldName in input))
+        return { status: "missing", value: null };
+    const raw = input[fieldName];
+    if (typeof raw !== "string" ||
+        raw.length === 0 ||
+        raw !== raw.trim() ||
+        hasControlCharacter(raw) ||
+        hasUnpairedUtf16Surrogate(raw) ||
+        Buffer.byteLength(raw, "utf8") > MAX_HOOK_HOST_IDENTITY_UTF8_BYTES) {
+        return { status: "invalid", value: null };
+    }
+    return { status: "ok", value: raw };
+}
+function unresolvedHostIdentity(status, provider, message) {
+    return { status, provider, rawSessionId: null, sessionId: null, message };
+}
+function canonicalHostSessionId(provider, rawSessionId) {
+    const encoded = Buffer.from(rawSessionId, "utf8").toString("base64url");
+    return `host:${provider}:v1:${encoded}`;
+}
+function resolvedHostIdentity(provider, rawSessionId) {
+    return {
+        status: "ok",
+        provider,
+        rawSessionId,
+        sessionId: canonicalHostSessionId(provider, rawSessionId),
+        message: null,
+    };
+}
+/**
+ * Resolve the stable conversation/session-family key documented by each host.
+ *
+ * - Codex: `session_id` (parent and subagents share it).
+ * - Claude Code: `session_id` (`agent_id` is deliberately not the owner key).
+ * - Cursor: `conversation_id`; simultaneous `session_id` must agree.
+ * - Grok/unknown: no guessed payload identity; callers keep explicit/env flow.
+ */
+export function resolveHookHostIdentity(host, payload) {
+    if (!HOST_IDENTITY_PROVIDERS.includes(host)) {
+        return unresolvedHostIdentity("unsupported", host, `Host ${host || "<empty>"} has no verified payload identity contract.`);
+    }
+    const provider = host;
+    const input = record(payload);
+    if (input === null) {
+        return unresolvedHostIdentity("invalid", provider, `${provider} hook payload is not an object.`);
+    }
+    if (provider === "codex" || provider === "claude") {
+        const session = identityField(input, "session_id");
+        if (session.status !== "ok") {
+            return unresolvedHostIdentity(session.status, provider, `${provider} hook payload ${session.status === "missing" ? "omits" : "has invalid"} session_id.`);
+        }
+        return resolvedHostIdentity(provider, session.value);
+    }
+    const conversation = identityField(input, "conversation_id");
+    if (conversation.status !== "ok") {
+        return unresolvedHostIdentity(conversation.status, provider, `Cursor hook payload ${conversation.status === "missing" ? "omits" : "has invalid"} conversation_id.`);
+    }
+    const simultaneousSession = identityField(input, "session_id");
+    if (simultaneousSession.status === "invalid") {
+        return unresolvedHostIdentity("invalid", provider, "Cursor hook payload has invalid session_id alongside conversation_id.");
+    }
+    if (simultaneousSession.status === "ok" && simultaneousSession.value !== conversation.value) {
+        return unresolvedHostIdentity("conflict", provider, "Cursor hook identity conflict: conversation_id and session_id differ.");
+    }
+    return resolvedHostIdentity(provider, conversation.value);
+}
+export const EXACT_LIFECYCLE_VERBS = [
+    "session:start",
+    "session:ready",
+    "session:end",
+    "occupancy:steal",
+    "occupancy:release",
+    "occupancy:heartbeat",
+    "swarm:launch",
+];
+const DIRECT_LIFECYCLE_VERBS = {
+    "session:start": "session:start",
+    "session:ready": "session:ready",
+    "session:end": "session:end",
+    "occupancy:steal": "occupancy:steal",
+    "occupancy:release": "occupancy:release",
+    "occupancy:heartbeat": "occupancy:heartbeat",
+    "swarm-launch": "swarm:launch",
+};
+const CANONICAL_OWNER_PATTERN = /^host:(?:codex|claude|cursor):v1:[A-Za-z0-9_-]+$/;
+// Shell expansion markers are deliberately absent: `$`/backticks for POSIX,
+// `@` splatting for PowerShell, and `%NAME%` expansion for command shells.
+// Backslashes are inspectable so Windows path-bearing lifecycle commands fail
+// closed, but they remain outside the auto-approved rewrite surface below.
+const INSPECTABLE_TOKEN_PATTERN = /^[A-Za-z0-9_./\\:+=,-]+$/;
+const LIFECYCLE_ARGUMENT_POLICIES = {
+    "session:start": {
+        booleanFlags: new Set([
+            "--json",
+            "--no-history",
+            "--read-only",
+            "--with-network",
+            "--rearm",
+            "--hard-budget",
+            "--compact",
+            "--steal",
+            "--confirm",
+        ]),
+        valueFlags: new Set([
+            "--tier",
+            "--defer",
+            "--task-size",
+            "--ceremony-task-size",
+            "--model-tier",
+            "--ceremony-model-tier",
+            "--project-shape",
+            "--ceremony-project-shape",
+            "--ceremony-depth",
+            "--max-turns",
+            "--max-budget",
+            "--session-id",
+            "--occupant",
+            "--project-root",
+        ]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "session:ready": {
+        booleanFlags: new Set(["--json", "--with-network"]),
+        valueFlags: new Set(["--repo", "--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "session:end": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:steal": {
+        booleanFlags: new Set(["--confirm"]),
+        valueFlags: new Set(["--occupant", "--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:release": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "occupancy:heartbeat": {
+        booleanFlags: new Set(),
+        valueFlags: new Set(["--session-id", "--project-root"]),
+        rewriteUnsafeFlags: new Set(["--project-root"]),
+    },
+    "swarm:launch": {
+        booleanFlags: new Set([
+            "--autonomous",
+            "--no-create-worktrees",
+            "--enforce-gates",
+            "--no-audit",
+        ]),
+        valueFlags: new Set([
+            "--stories",
+            "--paths",
+            "--group",
+            "--worktree-map",
+            "--base-branch",
+            "--allocation-plan-id",
+            "--batching-rationale",
+            "--operator-approval",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+            "--session-id",
+        ]),
+        rewriteUnsafeFlags: new Set([
+            "--paths",
+            "--worktree-map",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+            "--no-audit",
+        ]),
+        separateOnlyValueFlags: new Set([
+            "--stories",
+            "--paths",
+            "--group",
+            "--worktree-map",
+            "--base-branch",
+            "--allocation-plan-id",
+            "--batching-rationale",
+            "--operator-approval",
+            "--output",
+            "--gate-clearances",
+            "--project-root",
+        ]),
+    },
+};
+function lifecycleArgumentValueIsRewriteSafe(verb, flag, value) {
+    if (verb !== "swarm:launch" || flag !== "--stories")
+        return true;
+    // `swarm:launch --stories` accepts both logical IDs and filesystem paths.
+    // Only the ID form belongs in the auto-approved rewrite bridge; path-bearing
+    // invocations must keep the host's ordinary permission decision.
+    return value
+        .split(",")
+        .every((story) => story.length > 0 &&
+        !story.endsWith(".json") &&
+        !story.includes("/") &&
+        !story.includes("\\"));
+}
+/**
+ * Validate the complete CLI argument surface before returning an allow+rewrite.
+ * Path rebinding/destination flags and unknown/future flags are recognized but
+ * kept outside the auto-rewrite bridge. Supported hosts must carry the matching
+ * owner explicitly before those commands retain normal permission handling.
+ */
+function analyzeLifecycleArguments(verb, args) {
+    const policy = LIFECYCLE_ARGUMENT_POLICIES[verb];
+    let rewriteSafe = true;
+    let readOnly = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index] ?? "";
+        if (policy.booleanFlags.has(token)) {
+            if (verb === "session:start" && token === "--read-only")
+                readOnly = true;
+            if (policy.rewriteUnsafeFlags.has(token))
+                rewriteSafe = false;
+            continue;
+        }
+        const equals = token.indexOf("=");
+        if (equals > 0) {
+            const flag = token.slice(0, equals);
+            const value = token.slice(equals + 1);
+            if (!policy.valueFlags.has(flag)) {
+                rewriteSafe = false;
+                continue;
+            }
+            if (policy.rewriteUnsafeFlags.has(flag))
+                rewriteSafe = false;
+            if (policy.separateOnlyValueFlags?.has(flag) === true)
+                rewriteSafe = false;
+            // Keep malformed session identity visible to inspection so the
+            // dispatcher can deny ambiguity instead of silently skipping rewrite.
+            if (value.length === 0 && flag !== "--session-id")
+                rewriteSafe = false;
+            if (!lifecycleArgumentValueIsRewriteSafe(verb, flag, value))
+                rewriteSafe = false;
+            continue;
+        }
+        if (!policy.valueFlags.has(token)) {
+            rewriteSafe = false;
+            continue;
+        }
+        if (policy.rewriteUnsafeFlags.has(token))
+            rewriteSafe = false;
+        const value = args[index + 1];
+        if (value === undefined) {
+            if (token !== "--session-id")
+                rewriteSafe = false;
+            continue;
+        }
+        if (value.startsWith("--"))
+            rewriteSafe = false;
+        if (!lifecycleArgumentValueIsRewriteSafe(verb, token, value))
+            rewriteSafe = false;
+        // Match the real lifecycle parsers: known value flags consume the next
+        // argv token even when it begins with `--`. This prevents a swallowed
+        // `--session-id=...` from being mistaken for an effective owner.
+        index += 1;
+    }
+    return { rewriteSafe, readOnly };
+}
+/**
+ * Inspect single-space-separated lifecycle commands while excluding shell
+ * quoting, substitution, redirection, chaining, aliases, and wrappers.
+ * Windows path separators remain inspectable but make rewriting unsafe.
+ */
+function exactLifecycleInvocation(command) {
+    if (command.length === 0 || command !== command.trim())
+        return null;
+    const tokens = command.split(" ");
+    if (tokens.some((token) => token.length === 0 || !INSPECTABLE_TOKEN_PATTERN.test(token))) {
+        return null;
+    }
+    if (tokens.length < 2)
+        return null;
+    const executable = tokens[0];
+    const verb = tokens[1];
+    if (executable === "deft" || executable === "directive") {
+        const typedVerb = verb === undefined ? undefined : DIRECT_LIFECYCLE_VERBS[verb];
+        if (typedVerb === undefined)
+            return null;
+        const forwardedArgs = tokens.slice(2);
+        const { rewriteSafe, readOnly } = analyzeLifecycleArguments(typedVerb, forwardedArgs);
+        const requiresOwner = typedVerb !== "session:start" || !readOnly;
+        return {
+            verb: typedVerb,
+            task: false,
+            forwardedArgs,
+            rewriteSafe: rewriteSafe && forwardedArgs.every((token) => !token.includes("\\")),
+            requiresOwner,
+        };
+    }
+    if (executable !== "task")
+        return null;
+    if (!EXACT_LIFECYCLE_VERBS.includes(verb ?? ""))
+        return null;
+    const typedVerb = verb;
+    if (tokens.length === 2) {
+        return {
+            verb: typedVerb,
+            task: true,
+            forwardedArgs: [],
+            rewriteSafe: true,
+            requiresOwner: true,
+        };
+    }
+    // Go Task's canonical CLI_ARGS boundary. Flags without `--` are ambiguous
+    // Task CLI flags and must not receive an auto-approving rewrite.
+    if (tokens[2] !== "--")
+        return null;
+    const forwardedArgs = tokens.slice(3);
+    const { rewriteSafe, readOnly } = analyzeLifecycleArguments(typedVerb, forwardedArgs);
+    const requiresOwner = typedVerb !== "session:start" || !readOnly;
+    return {
+        verb: typedVerb,
+        task: true,
+        forwardedArgs,
+        rewriteSafe: rewriteSafe && forwardedArgs.every((token) => !token.includes("\\")),
+        requiresOwner,
+    };
+}
+function exactLifecyclePayload(payload) {
+    const toolName = hookToolName(payload);
+    if (toolName === null || !isShellTool(toolName)) {
+        return null;
+    }
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    if (toolInput === null || typeof toolInput.command !== "string")
+        return null;
+    const originalCommand = toolInput.command;
+    const invocation = exactLifecycleInvocation(originalCommand);
+    return invocation === null ? null : { invocation, originalCommand, toolInput };
+}
+/** Logical lifecycle verb for one exact, simple shell command; otherwise null. */
+export function exactLifecycleCommandVerb(payload) {
+    return exactLifecyclePayload(payload)?.invocation.verb ?? null;
+}
+function sessionIdArgs(verb, args) {
+    const policy = LIFECYCLE_ARGUMENT_POLICIES[verb];
+    const values = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i] ?? "";
+        if (token.startsWith("--session-id=")) {
+            const value = token.slice("--session-id=".length);
+            if (value.length === 0)
+                return { status: "invalid", values: [] };
+            values.push(value);
+            continue;
+        }
+        if (token === "--session-id") {
+            const value = args[i + 1];
+            if (value === undefined ||
+                value.length === 0 ||
+                (verb === "swarm:launch" && value.startsWith("--"))) {
+                return { status: "invalid", values: [] };
+            }
+            values.push(value);
+            i += 1;
+            continue;
+        }
+        if (token.indexOf("=") < 0 && policy.valueFlags.has(token) && args[i + 1] !== undefined)
+            i += 1;
+    }
+    if (values.length === 0)
+        return { status: "absent", values };
+    if (values.length !== 1)
+        return { status: "invalid", values };
+    return { status: "present", values };
+}
+/** Inspect one exact lifecycle command without requiring a host identity. */
+export function inspectExactLifecycleCommand(payload) {
+    const exact = exactLifecyclePayload(payload);
+    if (exact === null)
+        return null;
+    const session = sessionIdArgs(exact.invocation.verb, exact.invocation.forwardedArgs);
+    return {
+        verb: exact.invocation.verb,
+        task: exact.invocation.task,
+        rewriteSafe: exact.invocation.rewriteSafe,
+        requiresOwner: exact.invocation.requiresOwner,
+        sessionIdStatus: session.status,
+        sessionId: session.status === "present" ? (session.values[0] ?? null) : 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 function rewriteExactLifecycleCommand(payload, sessionId) {
+    if (!CANONICAL_OWNER_PATTERN.test(sessionId))
+        return null;
+    const exact = exactLifecyclePayload(payload);
+    if (exact === null)
+        return null;
+    const { invocation, originalCommand, toolInput } = exact;
+    if (!invocation.rewriteSafe || !invocation.requiresOwner)
+        return null;
+    const existing = sessionIdArgs(invocation.verb, invocation.forwardedArgs);
+    if (existing.status === "invalid")
+        return null;
+    if (existing.status === "present") {
+        const existingSessionId = existing.values[0] ?? "";
+        if (existingSessionId === sessionId)
+            return null;
+        return {
+            kind: "conflict",
+            verb: invocation.verb,
+            existingSessionId,
+            requestedSessionId: sessionId,
+            message: `Lifecycle command ${invocation.verb} already names a different ` +
+                "--session-id; refusing rewrite.",
+        };
+    }
+    const taskForwarding = invocation.task && originalCommand.split(" ").length === 2 ? " --" : "";
+    const rewrittenCommand = `${originalCommand}${taskForwarding} --session-id=${sessionId}`;
+    return {
+        kind: "rewrite",
+        verb: invocation.verb,
+        originalCommand,
+        rewrittenCommand,
+        updatedInput: { ...toolInput, command: rewrittenCommand },
+    };
+}
+//# sourceMappingURL=host-session-identity.js.map

package/dist/hooks/classify/index.d.ts

@@ -5,9 +5,10 @@
  * Policy / ritual / scope / permission emission stay in dispatcher + CLI adapter.
  */
 export { classifyHookPayload } from "./classify.js";
-export { hookMcpArgsText, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
+export { EXACT_LIFECYCLE_VERBS, type ExactLifecycleCommandConflict, type ExactLifecycleCommandInspection, type ExactLifecycleCommandResult, type ExactLifecycleCommandRewrite, type ExactLifecycleVerb, exactLifecycleCommandVerb, HOST_IDENTITY_PROVIDERS, type HookHostIdentityProvider, type HookHostIdentityResolution, type HookHostIdentityStatus, inspectExactLifecycleCommand, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, resolveHookHostIdentity, rewriteExactLifecycleCommand, } from "./host-session-identity.js";
+export { hookApplyPatchBodyPaths, hookMcpArgsText, hookMutationTargetPaths, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
 export { fieldPresent, fieldString, firstString, hookPayloadTopLevelKeys, record, toolInputRecord, } from "./payload.js";
-export { parseHookStdin, stripUtf8Bom } from "./stdin.js";
+export { applyPatchMutationPaths, parseHookStdin, stripUtf8Bom } from "./stdin.js";
 export { hookToolName, inferCursorDirectWriteToolName, type MissingToolNameInput, missingToolNameMessage, } from "./tool-name.js";
 export type { ClassifyHookHost, ClassifyHookPayloadInput, HookClassification, HookPayloadContext, HookWriteIntent, ParsedHookPayload, } from "./types.js";
 export { CLASSIFY_HOOK_HOSTS } from "./types.js";

package/dist/hooks/classify/index.js

@@ -5,9 +5,10 @@
  * Policy / ritual / scope / permission emission stay in dispatcher + CLI adapter.
  */
 export { classifyHookPayload } from "./classify.js";
-export { hookMcpArgsText, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
+export { EXACT_LIFECYCLE_VERBS, exactLifecycleCommandVerb, HOST_IDENTITY_PROVIDERS, inspectExactLifecycleCommand, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, resolveHookHostIdentity, rewriteExactLifecycleCommand, } from "./host-session-identity.js";
+export { hookApplyPatchBodyPaths, hookMcpArgsText, hookMutationTargetPaths, hookPathSet, hookShellCommand, hookWriteTargetPath, } from "./paths.js";
 export { fieldPresent, fieldString, firstString, hookPayloadTopLevelKeys, record, toolInputRecord, } from "./payload.js";
-export { parseHookStdin, stripUtf8Bom } from "./stdin.js";
+export { applyPatchMutationPaths, parseHookStdin, stripUtf8Bom } from "./stdin.js";
 export { hookToolName, inferCursorDirectWriteToolName, missingToolNameMessage, } from "./tool-name.js";
 export { CLASSIFY_HOOK_HOSTS } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/hooks/classify/paths.d.ts

@@ -7,6 +7,13 @@
  * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
  */
 export declare function hookWriteTargetPath(payload: unknown): string | null;
+/** ApplyPatch body paths from patch / unified_diff / diff fields. */
+export declare function hookApplyPatchBodyPaths(payload: unknown): string[];
+/**
+ * Declared write target plus ApplyPatch body members. Used to admit one
+ * effectiveRoot; a span across two Git toplevels is refused (#3794).
+ */
+export declare function hookMutationTargetPaths(payload: unknown): string[];
 /**
  * Best-effort shell command string from host PreToolUse payloads (#2711).
  * Hosts disagree on nesting (`tool_input.command` vs top-level `command`).

package/dist/hooks/classify/paths.js

@@ -3,6 +3,7 @@
  * No process I/O — does not resolve against projectRoot or realpath.
  */
 import { firstString, record, toolInputRecord } from "./payload.js";
+import { applyPatchMutationPaths } from "./stdin.js";
 /**
  * Best-effort write-target path from host PreToolUse payloads (#2625).
  * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
@@ -21,6 +22,40 @@ export function hookWriteTargetPath(payload) {
         input.path,
     ]);
 }
+/** ApplyPatch body paths from patch / unified_diff / diff fields. */
+export function hookApplyPatchBodyPaths(payload) {
+    const input = record(payload);
+    if (input === null)
+        return [];
+    const toolInput = toolInputRecord(input);
+    const patch = firstString([
+        toolInput?.patch,
+        toolInput?.unified_diff,
+        toolInput?.diff,
+        input.patch,
+        input.unified_diff,
+        input.diff,
+    ]);
+    return patch === null ? [] : applyPatchMutationPaths(patch);
+}
+/**
+ * Declared write target plus ApplyPatch body members. Used to admit one
+ * effectiveRoot; a span across two Git toplevels is refused (#3794).
+ */
+export function hookMutationTargetPaths(payload) {
+    const seen = new Set();
+    const out = [];
+    const push = (value) => {
+        if (value === null || value.length === 0 || seen.has(value))
+            return;
+        seen.add(value);
+        out.push(value);
+    };
+    push(hookWriteTargetPath(payload));
+    for (const path of hookApplyPatchBodyPaths(payload))
+        push(path);
+    return out;
+}
 /**
  * Best-effort shell command string from host PreToolUse payloads (#2711).
  * Hosts disagree on nesting (`tool_input.command` vs top-level `command`).

package/dist/hooks/classify/stdin.d.ts

@@ -4,6 +4,11 @@
  */
 import type { ParsedHookPayload } from "./types.js";
 export declare function stripUtf8Bom(raw: string): string;
+/**
+ * Paths named by ApplyPatch mutation headers, plus `*** Move to:` rename
+ * destinations. Order preserved, duplicates dropped.
+ */
+export declare function applyPatchMutationPaths(text: string): string[];
 /**
  * Parse host hook stdin text into a payload + parse context.
  * Empty → stdinEmpty; invalid JSON without free-form ApplyPatch → parseFailed.

package/dist/hooks/classify/stdin.js

@@ -6,9 +6,36 @@ const UTF8_BOM = "\uFEFF";
 const APPLY_PATCH_BEGIN_MARKER = "*** Begin Patch";
 /** Single-file Add/Update only — other *** … File: ops must fail closed (#2738 Greptile). */
 const APPLY_PATCH_MUTATION_LINE_RE = /^\*\*\* (Add File|Update File|Delete File|Move File|Rename File): (.+)$/gm;
+/**
+ * Canonical apply_patch spells a rename as `*** Update File:` followed by
+ * `*** Move to:`. The destination is a mutation target in its own right, so it
+ * must reach root admission; kept separate from the header regex above so the
+ * single-mutation #2738 synthesis contract is unchanged (#3794).
+ */
+const APPLY_PATCH_MOVE_DESTINATION_RE = /^\*\*\* Move to: (.+)$/gm;
 export function stripUtf8Bom(raw) {
     return raw.startsWith(UTF8_BOM) ? raw.slice(UTF8_BOM.length) : raw;
 }
+/**
+ * Paths named by ApplyPatch mutation headers, plus `*** Move to:` rename
+ * destinations. Order preserved, duplicates dropped.
+ */
+export function applyPatchMutationPaths(text) {
+    const paths = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const path = raw?.trim();
+        if (!path || seen.has(path))
+            return;
+        seen.add(path);
+        paths.push(path);
+    };
+    for (const match of text.matchAll(APPLY_PATCH_MUTATION_LINE_RE))
+        push(match[2]);
+    for (const match of text.matchAll(APPLY_PATCH_MOVE_DESTINATION_RE))
+        push(match[1]);
+    return paths;
+}
 function trySynthesizeFreeFormApplyPatch(normalized) {
     if (!normalized.includes(APPLY_PATCH_BEGIN_MARKER))
         return null;