@voybio/ace-swarm 0.2.4 → 2.4.0

package/dist/runtime-profile.d.ts

@@ -8,6 +8,31 @@ export declare const DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH = "agent-state/runti
 export declare const DEFAULT_EXECUTOR_MAX_TURNS = 6;
 export declare const DEFAULT_EXECUTOR_TURN_TIMEOUT_MS = 300000;
 export declare const DEFAULT_VERICIFY_BRIDGE_REL_PATH = "agent-state/vericify/ace-bridge.json";
+export type RuntimeModelClass = "frontier" | "mid" | "small_local";
+export declare const DEFAULT_STALL_WINDOW_MS = 300000;
+export declare const DEFAULT_TURN_BUDGET_MS = 1800000;
+export declare const DEFAULT_MAX_STALL_RESTARTS = 3;
+export declare const DEFAULT_INITIAL_BACKOFF_MS = 5000;
+export declare const DEFAULT_MAX_RETRY_BACKOFF_MS = 300000;
+export interface ModelClassLivenessDefaults {
+    turn_budget_ms: number;
+    stall_window_ms: number;
+    max_stall_restarts: number;
+    initial_backoff_ms: number;
+    max_retry_backoff_ms: number;
+}
+export interface SurgicalReadBudgets {
+    small_local: number;
+    mid: number;
+    frontier: number | null;
+}
+export interface ResolvedSurgicalReadBudget {
+    model_class: RuntimeModelClass;
+    read_file_lines_max_lines: number | null;
+}
+export declare const DEFAULT_SURGICAL_READ_BUDGETS: SurgicalReadBudgets;
+export declare function getLivenessDefaults(modelClass?: RuntimeModelClass): ModelClassLivenessDefaults;
+export declare function resolveEffectiveSurgicalReadBudget(profile: RuntimeProfile | undefined, modelClass?: RuntimeModelClass): ResolvedSurgicalReadBudget;
 export declare const DEFAULT_VERICIFY_PROCESS_POST_LOG_REL_PATH = "agent-state/vericify/process-posts.json";
 declare const runtimeProfileSchema: z.ZodObject<{
     ace_runtime_version: z.ZodLiteral<"1.0.0">;
@@ -41,6 +66,11 @@ declare const runtimeProfileSchema: z.ZodObject<{
     }, z.core.$strict>;
     tools: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         registry_path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        surgical_read_budgets: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            small_local: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            mid: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            frontier: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>>;
     autonomy: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         orchestrator_preflight: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -110,7 +140,9 @@ export declare function readRuntimeProfile(): RuntimeProfile;
 export declare function readRuntimePromptTemplate(): string;
 export declare function readRuntimeProfileState(): RuntimeProfileSnapshot;
 export declare function renderRuntimePrompt(templateContext: Record<string, unknown>): string;
+export declare function renderRuntimePromptFromSnapshot(snapshot: RuntimeProfileSnapshot, templateContext: Record<string, unknown>): string;
 export declare function getRuntimeProfilePath(): string;
 export declare function getRuntimeProfileSchemaPath(): string;
+export declare function getSurgicalReadBudget(modelClass: "frontier" | "mid" | "small_local" | undefined, profile?: RuntimeProfile): number | null;
 export {};
 //# sourceMappingURL=runtime-profile.d.ts.map

package/dist/runtime-profile.js

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { z } from "zod";
 import { DEFAULTS_ROOT, resolveWorkspaceArtifactPath, resolveWorkspaceRoot, } from "./helpers.js";
 import { getStoreStatSync, getWorkspaceStorePath, parseVirtualStorePath, readStoreBlobSync, readStoreBlobByPathSync, toVirtualStorePath, } from "./store/store-snapshot.js";
-import { appendStatusEvent } from "./status-events.js";
+import { appendStatusEventSafe } from "./status-events.js";
 import { DEFAULT_AUTONOMY_POLICY, DEFAULT_CONTINUITY_POLICY, } from "./ace-autonomy.js";
 export const RUNTIME_PROFILE_REL_PATH = "agent-state/ACE_WORKFLOW.md";
 export const RUNTIME_PROFILE_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json";
@@ -13,6 +13,57 @@ export const DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH = "agent-state/runtime-tool-
 export const DEFAULT_EXECUTOR_MAX_TURNS = 6;
 export const DEFAULT_EXECUTOR_TURN_TIMEOUT_MS = 300_000;
 export const DEFAULT_VERICIFY_BRIDGE_REL_PATH = "agent-state/vericify/ace-bridge.json";
+// Liveness defaults per model class
+export const DEFAULT_STALL_WINDOW_MS = 300_000; // 5 min — inter-progress cap
+export const DEFAULT_TURN_BUDGET_MS = 1_800_000; // 30 min — per-turn soft cap
+export const DEFAULT_MAX_STALL_RESTARTS = 3;
+export const DEFAULT_INITIAL_BACKOFF_MS = 5_000;
+export const DEFAULT_MAX_RETRY_BACKOFF_MS = 300_000;
+export const DEFAULT_SURGICAL_READ_BUDGETS = {
+    small_local: 200,
+    mid: 800,
+    frontier: null,
+};
+export function getLivenessDefaults(modelClass) {
+    switch (modelClass) {
+        case "small_local":
+            return {
+                turn_budget_ms: 3_600_000, // 60 min — slow models need generous cap
+                stall_window_ms: 180_000, // 3 min stall window
+                max_stall_restarts: 3,
+                initial_backoff_ms: 10_000,
+                max_retry_backoff_ms: 300_000,
+            };
+        case "mid":
+            return {
+                turn_budget_ms: 1_800_000, // 30 min
+                stall_window_ms: 300_000, // 5 min
+                max_stall_restarts: 3,
+                initial_backoff_ms: 5_000,
+                max_retry_backoff_ms: 180_000,
+            };
+        case "frontier":
+        default:
+            return {
+                turn_budget_ms: DEFAULT_TURN_BUDGET_MS,
+                stall_window_ms: DEFAULT_STALL_WINDOW_MS,
+                max_stall_restarts: DEFAULT_MAX_STALL_RESTARTS,
+                initial_backoff_ms: DEFAULT_INITIAL_BACKOFF_MS,
+                max_retry_backoff_ms: DEFAULT_MAX_RETRY_BACKOFF_MS,
+            };
+    }
+}
+function resolveSurgicalReadBudgetValue(budgets, modelClass) {
+    const resolved = budgets ?? DEFAULT_SURGICAL_READ_BUDGETS;
+    return resolved[modelClass] ?? null;
+}
+export function resolveEffectiveSurgicalReadBudget(profile, modelClass) {
+    const effectiveModelClass = modelClass ?? "frontier";
+    return {
+        model_class: effectiveModelClass,
+        read_file_lines_max_lines: resolveSurgicalReadBudgetValue(profile?.tools?.surgical_read_budgets, effectiveModelClass),
+    };
+}
 export const DEFAULT_VERICIFY_PROCESS_POST_LOG_REL_PATH = "agent-state/vericify/process-posts.json";
 const DEFAULT_RUNTIME_PROFILE_PATH = resolve(DEFAULTS_ROOT, RUNTIME_PROFILE_REL_PATH);
 const DEFAULT_RUNTIME_PROFILE_SCHEMA_PATH = resolve(DEFAULTS_ROOT, RUNTIME_PROFILE_SCHEMA_REL_PATH);
@@ -63,10 +114,22 @@ const runtimeProfileSchema = z
             .min(1)
             .optional()
             .default(DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH),
+        surgical_read_budgets: z
+            .object({
+            small_local: z.number().int().positive().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.small_local),
+            mid: z.number().int().positive().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.mid),
+            frontier: z.number().int().positive().nullable().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.frontier),
+        })
+            .strict()
+            .optional()
+            .default(DEFAULT_SURGICAL_READ_BUDGETS),
     })
         .strict()
         .optional()
-        .default({ registry_path: DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH }),
+        .default({
+        registry_path: DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH,
+        surgical_read_budgets: DEFAULT_SURGICAL_READ_BUDGETS,
+    }),
     autonomy: z
         .object({
         orchestrator_preflight: z.boolean().optional().default(true),
@@ -336,7 +399,7 @@ function parseRuntimeProfileContent(raw) {
 }
 function emitRuntimeProfileEvent(eventType, input) {
     try {
-        appendStatusEvent({
+        void appendStatusEventSafe({
             source_module: "capability-framework",
             event_type: eventType,
             status: eventType === "RUNTIME_PROFILE_INVALID" ? "fail" : "pass",
@@ -349,6 +412,8 @@ function emitRuntimeProfileEvent(eventType, input) {
                 signature: input.signature,
                 errors: input.errors,
             },
+        }).catch(() => {
+            // Runtime profile reads must not fail due to observability side effects.
         });
     }
     catch {
@@ -357,13 +422,16 @@ function emitRuntimeProfileEvent(eventType, input) {
 }
 function ensureLastGoodSnapshot() {
     const current = loadRuntimeProfile();
-    if (current.ok && lastGoodSnapshot)
-        return lastGoodSnapshot;
-    if (lastGoodSnapshot)
+    if (current.ok)
+        return current;
+    if (lastGoodSnapshot &&
+        lastGoodSnapshot.path === current.path &&
+        lastGoodSnapshot.source === current.source) {
         return lastGoodSnapshot;
+    }
     const packaged = loadRuntimeProfile(DEFAULT_RUNTIME_PROFILE_PATH);
-    if (packaged.ok && lastGoodSnapshot)
-        return lastGoodSnapshot;
+    if (packaged.ok)
+        return packaged;
     throw new Error(`Packaged ACE runtime profile is invalid: ${(packaged.ok ? [] : packaged.errors).join("; ")}`);
 }
 function resolveTemplatePath(context, path) {
@@ -511,14 +579,17 @@ export function readRuntimeProfileState() {
 }
 export function renderRuntimePrompt(templateContext) {
     const active = ensureLastGoodSnapshot();
+    return renderRuntimePromptFromSnapshot(active, templateContext);
+}
+export function renderRuntimePromptFromSnapshot(snapshot, templateContext) {
     const renderContext = {
-        ...active.profile,
-        runtime_profile_path: active.path,
-        runtime_profile_source: active.source,
-        prompt_template: active.prompt_template,
+        ...snapshot.profile,
+        runtime_profile_path: snapshot.path,
+        runtime_profile_source: snapshot.source,
+        prompt_template: snapshot.prompt_template,
         ...templateContext,
     };
-    return active.prompt_template.replace(/{{\s*([A-Za-z0-9_.-]+)\s*}}/g, (match, token) => {
+    return snapshot.prompt_template.replace(/{{\s*([A-Za-z0-9_.-]+)\s*}}/g, (match, token) => {
         const value = resolveTemplatePath(renderContext, token);
         return value === undefined ? match : stringifyTemplateValue(value);
     });
@@ -529,4 +600,9 @@ export function getRuntimeProfilePath() {
 export function getRuntimeProfileSchemaPath() {
     return DEFAULT_RUNTIME_PROFILE_SCHEMA_PATH;
 }
+export function getSurgicalReadBudget(modelClass, profile) {
+    const effectiveProfile = profile ?? readRuntimeProfile();
+    const budgets = effectiveProfile.tools?.surgical_read_budgets ?? DEFAULT_SURGICAL_READ_BUDGETS;
+    return budgets[modelClass ?? "frontier"] ?? null;
+}
 //# sourceMappingURL=runtime-profile.js.map

package/dist/runtime-tool-specs.d.ts

@@ -1,4 +1,6 @@
+import type { ToolCostClass } from "./store/repositories/local-model-runtime-repository.js";
 import { type ArtifactSource } from "./helpers.js";
+import { type RuntimeModelClass } from "./runtime-profile.js";
 import { type ValidationResult } from "./schemas.js";
 export declare const RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH = "agent-state/runtime-tool-specs.json";
 export declare const RUNTIME_TOOL_SPEC_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json";
@@ -64,5 +66,24 @@ export declare function readRuntimeToolRegistry(): RuntimeToolSpecRegistry;
 export declare function listRuntimeToolSpecs(): RuntimeToolSpec[];
 export declare function getRuntimeToolRegistryPath(): string;
 export declare function executeRuntimeTool(name: string, input: unknown, context?: RuntimeToolExecutionContext): Promise<RuntimeToolExecutionResult>;
+export type ModelClass = RuntimeModelClass;
+export declare const SMALL_LOCAL_PRIORITY_TOOL_NAMES: readonly ["outline_file", "astgrep_query", "list_workspace", "read_file_lines", "recall_context", "validate_framework", "run_orchestrator"];
+export interface FilteredToolCatalogEntry {
+    name: string;
+    description: string;
+    input_schema: RuntimeToolSchema;
+    cost_class: ToolCostClass;
+}
+export interface FilteredToolCatalog {
+    entries: FilteredToolCatalogEntry[];
+    model_class: ModelClass;
+    unavailable_tools: {
+        name: string;
+        reason: string;
+        reason_code: string;
+    }[];
+    tool_cost_class: Record<string, ToolCostClass>;
+}
+export declare function buildFilteredToolCatalog(modelClass: ModelClass | undefined, allowedTools?: string[]): FilteredToolCatalog;
 export {};
 //# sourceMappingURL=runtime-tool-specs.d.ts.map

package/dist/runtime-tool-specs.js

@@ -12,7 +12,7 @@ import { appendStatusEventSafe } from "./status-events.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { getWorkspaceStorePath, readStoreBlobSync, storeExistsSync, toVirtualStorePath, } from "./store/store-snapshot.js";
 import { operationalArtifactKey, } from "./store/store-artifacts.js";
-import { withStoreWriteQueue } from "./store/write-queue.js";
+import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 export const RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH = "agent-state/runtime-tool-specs.json";
 export const RUNTIME_TOOL_SPEC_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json";
 export const RUNTIME_TOOL_SPEC_SCHEMA_NAME = "runtime-tool-spec-registry@1.0.0";
@@ -113,7 +113,7 @@ async function persistToolInvocationArtifacts(callId, requestContent, responseCo
         return { requestPath, responsePath };
     }
     const storePath = getWorkspaceStorePath(workspaceRoot);
-    await withStoreWriteQueue(storePath, async () => {
+    await withStoreWriteCoordinator(storePath, async () => {
         const store = await openStore(storePath);
         try {
             await store.setBlob(runtimeToolArtifactKey(callId, "request"), requestContent);
@@ -123,7 +123,7 @@ async function persistToolInvocationArtifacts(callId, requestContent, responseCo
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "persistToolInvocationArtifacts" });
     return {
         requestPath: runtimeToolArtifactVirtualPath(callId, "request"),
         responsePath: runtimeToolArtifactVirtualPath(callId, "response"),
@@ -524,4 +524,79 @@ export async function executeRuntimeTool(name, input, context = {}) {
     });
     return result;
 }
+export const SMALL_LOCAL_PRIORITY_TOOL_NAMES = [
+    "outline_file",
+    "astgrep_query",
+    "list_workspace",
+    "read_file_lines",
+    "recall_context",
+    "validate_framework",
+    "run_orchestrator",
+];
+const HEAVY_TOOL_NAMES = new Set([
+    "read_workspace_file",
+    "write_workspace_file",
+    "safe_edit_file",
+    "astgrep_rewrite",
+]);
+function extractCostClass(tool) {
+    const desc = (tool.description ?? "").toLowerCase();
+    if (desc.includes("cost: cheap"))
+        return "cheap";
+    if (desc.includes("cost: moderate"))
+        return "moderate";
+    if (desc.includes("cost: heavy"))
+        return "heavy";
+    if (HEAVY_TOOL_NAMES.has(tool.name))
+        return "heavy";
+    if (["read_file_lines", "apply_patch", "diff_files"].includes(tool.name))
+        return "moderate";
+    return "cheap";
+}
+export function buildFilteredToolCatalog(modelClass, allowedTools) {
+    const allTools = listRuntimeToolSpecs();
+    const effectiveModelClass = modelClass ?? "frontier";
+    const allowed = allowedTools ? new Set(allowedTools) : null;
+    const unavailable = [];
+    let entries = [];
+    for (const tool of allTools) {
+        if (allowed !== null && !allowed.has(tool.name)) {
+            unavailable.push({
+                name: tool.name,
+                reason: "Not in allowed_tools for this session",
+                reason_code: "workspace_disabled",
+            });
+            continue;
+        }
+        const costClass = extractCostClass(tool);
+        let description = tool.description;
+        if (effectiveModelClass === "small_local" && costClass === "heavy") {
+            description = `[cost: heavy — prefer surgical alternatives] ${description}`;
+        }
+        entries.push({
+            name: tool.name,
+            description,
+            input_schema: tool.input_schema,
+            cost_class: costClass,
+        });
+    }
+    if (effectiveModelClass === "small_local" || effectiveModelClass === "mid") {
+        const priority = new Map(SMALL_LOCAL_PRIORITY_TOOL_NAMES.map((name, idx) => [name, idx]));
+        entries.sort((a, b) => {
+            const pa = priority.get(a.name) ?? 999;
+            const pb = priority.get(b.name) ?? 999;
+            return pa - pb;
+        });
+    }
+    const toolCostClass = {};
+    for (const e of entries) {
+        toolCostClass[e.name] = e.cost_class;
+    }
+    return {
+        entries,
+        model_class: effectiveModelClass,
+        unavailable_tools: unavailable,
+        tool_cost_class: toolCostClass,
+    };
+}
 //# sourceMappingURL=runtime-tool-specs.js.map

package/dist/safe-edit.d.ts

@@ -49,4 +49,11 @@ export declare function diffContents(original: string, updated: string): DiffRes
 export declare function diffFiles(pathA: string, pathB: string): DiffResult & {
     error?: string;
 };
+export interface ApplyPatchInput {
+    path: string;
+    patch: string;
+    validation_command?: string;
+    test_command?: string;
+}
+export declare function applyPatch(input: ApplyPatchInput): SafeEditResult;
 //# sourceMappingURL=safe-edit.d.ts.map

package/dist/safe-edit.js

@@ -2,10 +2,11 @@
  * Safe-edit module: copy → modify → validate → swap pattern.
  * Prevents bricking by never leaving core files in a broken state.
  */
-import { copyFileSync, existsSync, mkdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdtempSync, mkdirSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { WORKSPACE_ROOT, safeRead, wsPath } from "./helpers.js";
 import { isInside, isReadError, normalizeRelPath } from "./shared.js";
 const STAGING_DIR = ".ace-staging";
@@ -19,14 +20,56 @@ function ensureDir(dirPath) {
     if (!existsSync(dirPath))
         mkdirSync(dirPath, { recursive: true });
 }
-function runValidation(validationCmd, testCmd) {
+function resolveWorkspaceTarget(inputPath) {
+    const absPath = resolve(WORKSPACE_ROOT, inputPath);
+    if (!isInside(WORKSPACE_ROOT, absPath)) {
+        return { error: `Path escapes workspace root: ${inputPath}`, absPath };
+    }
+    return {
+        absPath,
+        relPath: normalizeRelPath(relative(WORKSPACE_ROOT, absPath)),
+    };
+}
+function shouldCopyIntoStaging(src) {
+    const rel = normalizeRelPath(relative(WORKSPACE_ROOT, src));
+    if (!rel || rel === ".")
+        return true;
+    const first = rel.split("/")[0];
+    return !new Set([".ace-staging", ".git", "node_modules", ".npm-cache"]).has(first);
+}
+function prepareStagedWorkspace(stagingDir) {
+    const stagedWorkspace = mkdtempSync(resolve(tmpdir(), "ace-staged-workspace-"));
+    rmSync(stagedWorkspace, { recursive: true, force: true });
+    mkdirSync(stagedWorkspace, { recursive: true });
+    cpSync(WORKSPACE_ROOT, stagedWorkspace, {
+        recursive: true,
+        dereference: false,
+        filter: (src) => shouldCopyIntoStaging(src),
+    });
+    const rootNodeModules = resolve(WORKSPACE_ROOT, "node_modules");
+    if (existsSync(rootNodeModules)) {
+        symlinkSync(rootNodeModules, resolve(stagedWorkspace, "node_modules"), "dir");
+    }
+    writeFileSync(resolve(stagingDir, "workspace-path.txt"), stagedWorkspace, "utf-8");
+    return stagedWorkspace;
+}
+function workspacePathIn(root, relPath) {
+    return resolve(root, relPath);
+}
+function swapTargetContent(absPath, content) {
+    ensureDir(dirname(absPath));
+    const swapPath = `${absPath}.ace-swap.${process.pid}.${Date.now()}`;
+    writeFileSync(swapPath, content, "utf-8");
+    renameSync(swapPath, absPath);
+}
+function runValidation(validationCmd, testCmd, cwd = WORKSPACE_ROOT) {
     let validation_passed;
     let validation_output;
     let test_passed;
     let test_output;
     if (validationCmd) {
         const res = spawnSync("sh", ["-c", validationCmd], {
-            cwd: WORKSPACE_ROOT,
+            cwd,
             encoding: "utf-8",
             timeout: 60_000,
             maxBuffer: 4 * 1024 * 1024,
@@ -36,7 +79,7 @@ function runValidation(validationCmd, testCmd) {
     }
     if (testCmd && (validation_passed === undefined || validation_passed)) {
         const res = spawnSync("sh", ["-c", testCmd], {
-            cwd: WORKSPACE_ROOT,
+            cwd,
             encoding: "utf-8",
             timeout: 120_000,
             maxBuffer: 4 * 1024 * 1024,
@@ -51,84 +94,80 @@ function runValidation(validationCmd, testCmd) {
 // Safe edit (copy → modify → validate → swap)
 // ────────────────────────────────────────────────────────────────────
 export function safeEditFile(input) {
-    const absPath = resolve(WORKSPACE_ROOT, input.path);
-    // ── Workspace boundary guard ──────────────────────────────────────
-    if (!isInside(WORKSPACE_ROOT, absPath)) {
+    const target = resolveWorkspaceTarget(input.path);
+    if ("error" in target) {
         return {
             ok: false,
-            original_path: absPath,
+            original_path: target.absPath,
             staging_path: "",
             original_hash: "none",
             new_hash: "none",
-            error: `Path escapes workspace root: ${input.path}`,
+            error: target.error,
             restored: false,
         };
     }
-    const relPath = normalizeRelPath(input.path);
+    const { absPath, relPath } = target;
     const timestamp = Date.now();
     const originalContent = safeRead(input.path);
     const isNew = isReadError(originalContent);
     const originalHash = isNew ? "none" : fileHash(originalContent);
-    const newHash = fileHash(input.content);
+    const stagedNewHash = fileHash(input.content);
     // Step 1: Create staging directory
     const stagingDir = wsPath(STAGING_DIR, `${timestamp}-${isNew ? "new" : originalHash.slice(0, 8)}`);
     ensureDir(stagingDir);
     const flatName = relPath.replace(/\//g, "__");
     const stagingNew = resolve(stagingDir, `new__${flatName}`);
     writeFileSync(stagingNew, input.content, "utf-8");
+    const stagedWorkspace = prepareStagedWorkspace(stagingDir);
+    const stagedTarget = workspacePathIn(stagedWorkspace, relPath);
+    ensureDir(dirname(stagedTarget));
+    writeFileSync(stagedTarget, input.content, "utf-8");
     // Step 2: If file exists, copy original to staging + backup
     let backupPath;
     if (!isNew) {
         const stagingOriginal = resolve(stagingDir, `original__${flatName}`);
         writeFileSync(stagingOriginal, originalContent, "utf-8");
-        if (input.backup !== false) {
-            backupPath = `${absPath}.ace-backup.${originalHash.slice(0, 8)}`;
-            copyFileSync(absPath, backupPath);
-        }
     }
-    // Step 3: Write new content
-    ensureDir(dirname(absPath));
-    writeFileSync(absPath, input.content, "utf-8");
-    // Step 4: Run validation/tests
+    // Step 3: Run validation/tests against the staged workspace.
+    let check;
     if (input.validation_command || input.test_command) {
-        const check = runValidation(input.validation_command, input.test_command);
+        check = runValidation(input.validation_command, input.test_command, stagedWorkspace);
         if (!check.passed) {
-            // ROLLBACK: restore original content
-            if (!isNew) {
-                writeFileSync(absPath, originalContent, "utf-8");
-            }
-            else {
-                // Remove newly created file
-                try {
-                    unlinkSync(absPath);
-                }
-                catch {
-                    /* best effort */
-                }
-            }
             return {
                 ok: false,
                 original_path: absPath,
                 staging_path: stagingDir,
                 backup_path: backupPath,
                 original_hash: originalHash,
-                new_hash: newHash,
+                new_hash: stagedNewHash,
                 validation_passed: check.validation_passed,
                 validation_output: check.validation_output,
                 test_passed: check.test_passed,
                 test_output: check.test_output,
-                error: "Validation/test failed — original restored",
+                error: "Validation/test failed — staged change not promoted",
                 restored: true,
             };
         }
     }
+    // Step 4: Promote staged content to the real target only after checks pass.
+    if (!isNew && input.backup !== false) {
+        backupPath = `${absPath}.ace-backup.${originalHash.slice(0, 8)}`;
+        copyFileSync(absPath, backupPath);
+    }
+    const promotedContent = readFileSync(stagedTarget, "utf-8");
+    const promotedHash = fileHash(promotedContent);
+    swapTargetContent(absPath, promotedContent);
     return {
         ok: true,
         original_path: absPath,
         staging_path: stagingDir,
         backup_path: backupPath,
         original_hash: originalHash,
-        new_hash: newHash,
+        new_hash: promotedHash,
+        validation_passed: check?.validation_passed,
+        validation_output: check?.validation_output,
+        test_passed: check?.test_passed,
+        test_output: check?.test_output,
     };
 }
 // ────────────────────────────────────────────────────────────────────
@@ -252,4 +291,91 @@ export function diffFiles(pathA, pathB) {
     }
     return diffContents(contentA, contentB);
 }
+export function applyPatch(input) {
+    const target = resolveWorkspaceTarget(input.path);
+    if ("error" in target) {
+        return {
+            ok: false,
+            original_path: target.absPath,
+            staging_path: "",
+            original_hash: "none",
+            new_hash: "none",
+            error: target.error,
+            restored: false,
+        };
+    }
+    const { absPath, relPath } = target;
+    const originalContent = safeRead(input.path);
+    const isNew = isReadError(originalContent);
+    const originalHash = isNew ? "none" : fileHash(originalContent);
+    const timestamp = Date.now();
+    const stagingDir = wsPath(STAGING_DIR, `${timestamp}-patch-${isNew ? "new" : originalHash.slice(0, 8)}`);
+    ensureDir(stagingDir);
+    const stagedWorkspace = prepareStagedWorkspace(stagingDir);
+    const stagedTarget = workspacePathIn(stagedWorkspace, relPath);
+    ensureDir(dirname(stagedTarget));
+    if (isNew && !existsSync(stagedTarget))
+        writeFileSync(stagedTarget, "", "utf-8");
+    const tmpPatch = resolve(stagingDir, `${basename(relPath)}.${timestamp}.patch`);
+    try {
+        writeFileSync(tmpPatch, input.patch, "utf8");
+        const patchResult = spawnSync("patch", [stagedTarget, tmpPatch], {
+            encoding: "utf8",
+            cwd: stagedWorkspace,
+        });
+        if (patchResult.status !== 0) {
+            return {
+                ok: false,
+                original_path: absPath,
+                staging_path: stagingDir,
+                original_hash: originalHash,
+                new_hash: "none",
+                error: `patch command failed: ${patchResult.stderr || patchResult.stdout}`,
+                restored: true,
+            };
+        }
+        const patchedContent = readFileSync(stagedTarget, "utf-8");
+        const newHash = fileHash(patchedContent);
+        const check = runValidation(input.validation_command, input.test_command, stagedWorkspace);
+        if (!check.passed) {
+            return {
+                ok: false,
+                original_path: absPath,
+                staging_path: stagingDir,
+                original_hash: originalHash,
+                new_hash: newHash,
+                validation_passed: check.validation_passed,
+                validation_output: check.validation_output,
+                test_passed: check.test_passed,
+                test_output: check.test_output,
+                error: "Validation/test failed — staged patch not promoted",
+                restored: true,
+            };
+        }
+        let backupPath;
+        if (!isNew) {
+            backupPath = `${absPath}.ace-backup.${originalHash.slice(0, 8)}`;
+            copyFileSync(absPath, backupPath);
+        }
+        swapTargetContent(absPath, patchedContent);
+        return {
+            ok: true,
+            original_path: absPath,
+            staging_path: stagingDir,
+            backup_path: backupPath,
+            original_hash: originalHash,
+            new_hash: newHash,
+            validation_passed: check.validation_passed,
+            validation_output: check.validation_output,
+            test_passed: check.test_passed,
+            test_output: check.test_output,
+        };
+    }
+    finally {
+        try {
+            unlinkSync(tmpPatch);
+        }
+        catch { /* ignore */ }
+    }
+}
 //# sourceMappingURL=safe-edit.js.map