agentic-engineering-harness 0.6.8 → 0.6.10

package/dist/agents/permissions.d.ts

@@ -1,5 +1,32 @@
 import type { HarnessProjectConfig } from "../core/types.js";
 import type { AgentExecutionSelection } from "./types.js";
+export type OpenCodeAgentBindingSource = "aeh-managed" | "explicit";
+export interface OpenCodeAgentBinding {
+    agentId: string;
+    source: OpenCodeAgentBindingSource;
+    managed: boolean;
+}
+export interface OpenCodeRuntimeProjection {
+    binding: OpenCodeAgentBinding;
+    config: Record<string, unknown>;
+    env: Record<string, string>;
+}
 export declare function validateExecutionCapabilities(selection: AgentExecutionSelection, transport: string): string[];
 export declare function permissionSummary(selection: AgentExecutionSelection): string;
-export declare function buildOpenCodeRuntimeConfig(selection: AgentExecutionSelection, config?: HarnessProjectConfig): Record<string, unknown>;
+/**
+ * Resolve the concrete OpenCode execution identity for an AEH logical agent.
+ *
+ * Explicit nativeAgent is an externally-authored OpenCode primary/all agent and
+ * is preserved exactly. Otherwise AEH owns the native identity and injects a
+ * primary agent with a deterministic collision-resistant name into the
+ * session-local OpenCode config.
+ */
+export declare function resolveOpenCodeAgentBinding(selection: AgentExecutionSelection): OpenCodeAgentBinding;
+/**
+ * Compile the inline OpenCode configuration used by direct, Podman and Paseo
+ * transports. OPENCODE_CONFIG_CONTENT is loaded after ordinary user/project
+ * config, so the AEH-managed identity and policy are deterministic without
+ * mutating the user's global OpenCode configuration.
+ */
+export declare function buildOpenCodeRuntimeConfig(selection: AgentExecutionSelection, config?: HarnessProjectConfig, binding?: OpenCodeAgentBinding): Record<string, unknown>;
+export declare function compileOpenCodeRuntimeProjection(selection: AgentExecutionSelection, config?: HarnessProjectConfig): OpenCodeRuntimeProjection;

package/dist/agents/permissions.js

@@ -1,30 +1,189 @@
-export function validateExecutionCapabilities(selection, transport) { const issues = []; if (selection.nativeAgent && selection.runtimeCapabilities.nativeAgent === false)
-    issues.push(`Runtime ${selection.runtimeName} cannot select native agent ${selection.nativeAgent}.`); if (selection.nativeAgent && transport === "paseo" && selection.runtimeCapabilities.nativeAgentViaPaseo !== true)
-    issues.push(`Agent ${selection.logicalAgent} requires nativeAgent=${selection.nativeAgent}, but runtime ${selection.runtimeName} does not declare nativeAgentViaPaseo. Use transport=direct/podman or configure a Paseo provider that exposes this native agent.`); if (selection.variant && selection.runtimeCapabilities.variantSelection === false)
-    issues.push(`Runtime ${selection.runtimeName} cannot select variant ${selection.variant}.`); if (selection.role === "implementer" && selection.permissions.write === "deny")
-    issues.push(`Implementer ${selection.logicalAgent} denies write permission.`); if ((selection.role === "reviewer" || selection.role === "validator") && selection.permissions.write === "allow")
-    issues.push(`${selection.role} ${selection.logicalAgent} explicitly allows writes; read-only roles should use write=deny unless intentionally mutating.`); if (selection.role === "orchestrator" && selection.permissions.delegate === "deny")
-    issues.push(`Orchestrator ${selection.logicalAgent} denies delegation.`); return issues; }
-export function permissionSummary(selection) { return Object.entries(selection.permissions).map(([key, value]) => `${key}=${value}`).join(", ") || "unspecified"; }
-export function buildOpenCodeRuntimeConfig(selection, config) { const permission = {}; const p = selection.permissions; if (p.read)
-    permission.read = p.read; if (p.write)
-    permission.edit = p.write; if (p.network) {
-    permission.webfetch = p.network;
-    permission.websearch = p.network;
-} if (p.delegate)
-    permission.task = p.delegate; const bash = buildBashPermission(p.shell, p.gitWrite); if (bash)
-    permission.bash = bash; if (selection.skills.length && !selection.skills.includes("*"))
-    permission.skill = Object.fromEntries([["*", "deny"], ...selection.skills.map((skill) => [skill, "allow"])]); const mcp = {}; const tools = {}; const configured = config?.mcp?.servers ?? {}; for (const [name, server] of Object.entries(configured)) {
-    const selected = selection.mcps.includes(name) && server.enabled !== false;
-    tools[`${name}_*`] = selected;
-    if (selected)
-        mcp[name] = toOpenCodeMcp(server);
-} for (const name of selection.mcps)
-    if (!configured[name])
-        tools[`${name}_*`] = true; return { $schema: "https://opencode.ai/config.json", permission, ...(Object.keys(mcp).length ? { mcp } : {}), ...(Object.keys(tools).length ? { tools } : {}) }; }
-function toOpenCodeMcp(server) { if (server.type === "local")
-    return { type: "local", command: server.command, enabled: true, ...(server.environment ? { environment: server.environment } : {}), ...(server.timeoutMs ? { timeout: server.timeoutMs } : {}) }; return { type: "remote", url: server.url, enabled: true, ...(server.headers ? { headers: server.headers } : {}), ...(server.oauth !== undefined ? { oauth: server.oauth } : {}), ...(server.timeoutMs ? { timeout: server.timeoutMs } : {}) }; }
-function buildBashPermission(shell, gitWrite) { if (!gitWrite)
-    return shell; const result = { "*": shell ?? "ask" }; for (const pattern of ["git add *", "git commit *", "git push *", "git tag *", "git checkout *", "git switch *", "git reset *", "git clean *", "git restore *", "git merge *", "git rebase *", "git cherry-pick *"])
-    result[pattern] = gitWrite; return result; }
+import { createHash } from "node:crypto";
+export function validateExecutionCapabilities(selection, transport) {
+    const issues = [];
+    if (selection.nativeAgent && selection.runtimeCapabilities.nativeAgent === false) {
+        issues.push(`Runtime ${selection.runtimeName} cannot select native agent ${selection.nativeAgent}.`);
+    }
+    const nativeAgentViaPaseo = selection.runtimeCapabilities.nativeAgentViaPaseo === true ||
+        (selection.runtimeAdapter === "opencode" && selection.paseoProvider === "opencode");
+    if (selection.nativeAgent && transport === "paseo" && !nativeAgentViaPaseo) {
+        issues.push(`Agent ${selection.logicalAgent} requires nativeAgent=${selection.nativeAgent}, but runtime ${selection.runtimeName} does not support that native agent through Paseo.`);
+    }
+    if (selection.variant && selection.runtimeCapabilities.variantSelection === false) {
+        issues.push(`Runtime ${selection.runtimeName} cannot select variant ${selection.variant}.`);
+    }
+    if (selection.role === "implementer" && selection.permissions.write === "deny") {
+        issues.push(`Implementer ${selection.logicalAgent} denies write permission.`);
+    }
+    if ((selection.role === "reviewer" || selection.role === "validator") &&
+        selection.permissions.write === "allow") {
+        issues.push(`${selection.role} ${selection.logicalAgent} explicitly allows writes; read-only roles should use write=deny unless intentionally mutating.`);
+    }
+    if (selection.role === "orchestrator" && selection.permissions.delegate === "deny") {
+        issues.push(`Orchestrator ${selection.logicalAgent} denies delegation.`);
+    }
+    return issues;
+}
+export function permissionSummary(selection) {
+    return (Object.entries(selection.permissions)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(", ") || "unspecified");
+}
+/**
+ * Resolve the concrete OpenCode execution identity for an AEH logical agent.
+ *
+ * Explicit nativeAgent is an externally-authored OpenCode primary/all agent and
+ * is preserved exactly. Otherwise AEH owns the native identity and injects a
+ * primary agent with a deterministic collision-resistant name into the
+ * session-local OpenCode config.
+ */
+export function resolveOpenCodeAgentBinding(selection) {
+    const explicit = selection.nativeAgent?.trim();
+    if (explicit) {
+        return { agentId: explicit, source: "explicit", managed: false };
+    }
+    return {
+        agentId: managedOpenCodeAgentId(selection.logicalAgent),
+        source: "aeh-managed",
+        managed: true
+    };
+}
+/**
+ * Compile the inline OpenCode configuration used by direct, Podman and Paseo
+ * transports. OPENCODE_CONFIG_CONTENT is loaded after ordinary user/project
+ * config, so the AEH-managed identity and policy are deterministic without
+ * mutating the user's global OpenCode configuration.
+ */
+export function buildOpenCodeRuntimeConfig(selection, config, binding = resolveOpenCodeAgentBinding(selection)) {
+    const permission = buildOpenCodePermission(selection);
+    const mcp = {};
+    const tools = {};
+    const configured = config?.mcp?.servers ?? {};
+    for (const [name, server] of Object.entries(configured)) {
+        const selected = selection.mcps.includes(name) && server.enabled !== false;
+        tools[`${name}_*`] = selected;
+        if (selected)
+            mcp[name] = toOpenCodeMcp(server);
+    }
+    for (const name of selection.mcps) {
+        if (!configured[name])
+            tools[`${name}_*`] = true;
+    }
+    const managedAgent = binding.managed
+        ? {
+            agent: {
+                [binding.agentId]: {
+                    mode: "primary",
+                    description: selection.description ??
+                        `AEH-managed OpenCode execution identity for ${selection.logicalAgent}.`,
+                    model: selection.modelId,
+                    prompt: `AEH execution identity: ${selection.logicalAgent}. Follow the task-scoped AEH charter, frozen control-plane context, permissions and acceptance criteria supplied with each turn.`,
+                    ...(selection.variant ? { variant: selection.variant } : {}),
+                    ...(selection.temperature !== undefined
+                        ? { temperature: selection.temperature }
+                        : {}),
+                    ...(Object.keys(permission).length ? { permission } : {})
+                }
+            },
+            default_agent: binding.agentId
+        }
+        : {};
+    return {
+        $schema: "https://opencode.ai/config.json",
+        permission,
+        ...managedAgent,
+        ...(Object.keys(mcp).length ? { mcp } : {}),
+        ...(Object.keys(tools).length ? { tools } : {})
+    };
+}
+export function compileOpenCodeRuntimeProjection(selection, config) {
+    const binding = resolveOpenCodeAgentBinding(selection);
+    const runtimeConfig = buildOpenCodeRuntimeConfig(selection, config, binding);
+    return {
+        binding,
+        config: runtimeConfig,
+        env: {
+            OPENCODE_CONFIG_CONTENT: JSON.stringify(runtimeConfig)
+        }
+    };
+}
+function buildOpenCodePermission(selection) {
+    const permission = {};
+    const p = selection.permissions;
+    if (p.read)
+        permission.read = p.read;
+    if (p.write)
+        permission.edit = p.write;
+    if (p.network) {
+        permission.webfetch = p.network;
+        permission.websearch = p.network;
+    }
+    if (p.delegate)
+        permission.task = p.delegate;
+    const bash = buildBashPermission(p.shell, p.gitWrite);
+    if (bash)
+        permission.bash = bash;
+    if (selection.skills.length && !selection.skills.includes("*")) {
+        permission.skill = Object.fromEntries([
+            ["*", "deny"],
+            ...selection.skills.map((skill) => [skill, "allow"])
+        ]);
+    }
+    return permission;
+}
+function managedOpenCodeAgentId(logicalAgent) {
+    const original = logicalAgent.trim();
+    if (!original)
+        throw new Error("AEH logical agent name is required for OpenCode identity.");
+    const slug = original
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent";
+    const normalizedOriginal = original.toLowerCase();
+    if (slug === normalizedOriginal)
+        return `aeh-${slug}`;
+    const digest = createHash("sha256").update(original).digest("hex").slice(0, 8);
+    return `aeh-${slug}-${digest}`;
+}
+function toOpenCodeMcp(server) {
+    if (server.type === "local") {
+        return {
+            type: "local",
+            command: server.command,
+            enabled: true,
+            ...(server.environment ? { environment: server.environment } : {}),
+            ...(server.timeoutMs ? { timeout: server.timeoutMs } : {})
+        };
+    }
+    return {
+        type: "remote",
+        url: server.url,
+        enabled: true,
+        ...(server.headers ? { headers: server.headers } : {}),
+        ...(server.oauth !== undefined ? { oauth: server.oauth } : {}),
+        ...(server.timeoutMs ? { timeout: server.timeoutMs } : {})
+    };
+}
+function buildBashPermission(shell, gitWrite) {
+    if (!gitWrite)
+        return shell;
+    const result = { "*": shell ?? "ask" };
+    for (const pattern of [
+        "git add *",
+        "git commit *",
+        "git push *",
+        "git tag *",
+        "git checkout *",
+        "git switch *",
+        "git reset *",
+        "git clean *",
+        "git restore *",
+        "git merge *",
+        "git rebase *",
+        "git cherry-pick *"
+    ]) {
+        result[pattern] = gitWrite;
+    }
+    return result;
+}
 //# sourceMappingURL=permissions.js.map

package/dist/agents/permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/agents/permissions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/agents/permissions.ts"],"names":[],"mappings":"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"}

package/dist/operations/completion.d.ts

@@ -0,0 +1,26 @@
+import { dispatchManagedPaseoAgent } from "../paseo/runtime.js";
+import { recordPaseoTrace } from "../paseo/trace.js";
+import type { OperationRecord } from "./state.js";
+export type OperationCompletionStatus = "PENDING" | "SENT" | "FAILED" | "DISABLED";
+export interface OperationCompletionTarget {
+    version: 1;
+    operationId: string;
+    agentId: string;
+    source?: string;
+    status: OperationCompletionStatus;
+    registeredAt: string;
+    attemptedAt?: string;
+    sentAt?: string;
+    failedAt?: string;
+    error?: string;
+}
+export interface OperationCompletionDeps {
+    dispatch?: typeof dispatchManagedPaseoAgent;
+    trace?: typeof recordPaseoTrace;
+}
+export declare function operationCompletionFile(root: string, operationId: string): string;
+export declare function registerOperationCompletionTarget(root: string, operationId: string, agentId: string, source?: string, trace?: typeof recordPaseoTrace): Promise<OperationCompletionTarget>;
+export declare function disableOperationCompletionTarget(root: string, operationId: string, reason: string, trace?: typeof recordPaseoTrace): Promise<void>;
+export declare function loadOperationCompletionTarget(root: string, operationId: string): Promise<OperationCompletionTarget | undefined>;
+export declare function notifyOperationCompletion(root: string, operation: OperationRecord, deps?: OperationCompletionDeps): Promise<OperationCompletionTarget | undefined>;
+export declare function completionPrompt(operation: OperationRecord): string;

package/dist/operations/completion.js

@@ -0,0 +1,152 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { dispatchManagedPaseoAgent } from "../paseo/runtime.js";
+import { recordPaseoTrace } from "../paseo/trace.js";
+export function operationCompletionFile(root, operationId) {
+    return path.resolve(root, ".harness/operations", `${safeId(operationId)}.completion.json`);
+}
+export async function registerOperationCompletionTarget(root, operationId, agentId, source, trace = recordPaseoTrace) {
+    const target = {
+        version: 1,
+        operationId,
+        agentId: requiredId(agentId, "agent id"),
+        source,
+        status: "PENDING",
+        registeredAt: new Date().toISOString()
+    };
+    await persist(root, target);
+    await trace(root, "operation.callback.registered", {
+        operationId,
+        agentId: target.agentId,
+        source: source ?? "unknown"
+    });
+    return target;
+}
+export async function disableOperationCompletionTarget(root, operationId, reason, trace = recordPaseoTrace) {
+    const target = await loadOperationCompletionTarget(root, operationId);
+    if (!target || target.status === "SENT")
+        return;
+    const disabled = {
+        ...target,
+        status: "DISABLED",
+        attemptedAt: new Date().toISOString(),
+        error: reason
+    };
+    await persist(root, disabled);
+    await trace(root, "operation.callback.disabled", {
+        operationId,
+        agentId: target.agentId,
+        reason
+    });
+}
+export async function loadOperationCompletionTarget(root, operationId) {
+    try {
+        const value = JSON.parse(await fs.readFile(operationCompletionFile(root, operationId), "utf8"));
+        if (value.version !== 1 ||
+            value.operationId !== operationId ||
+            !value.agentId ||
+            !["PENDING", "SENT", "FAILED", "DISABLED"].includes(value.status)) {
+            throw new Error("invalid completion target record");
+        }
+        return value;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function notifyOperationCompletion(root, operation, deps = {}) {
+    const target = await loadOperationCompletionTarget(root, operation.id);
+    if (!target || target.status === "SENT" || target.status === "DISABLED")
+        return target;
+    const dispatch = deps.dispatch ?? dispatchManagedPaseoAgent;
+    const trace = deps.trace ?? recordPaseoTrace;
+    const attemptedAt = new Date().toISOString();
+    try {
+        const result = await dispatch(root, target.agentId, completionPrompt(operation), 60);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || result.stdout || `Paseo dispatch exited with code ${result.exitCode}`);
+        }
+        const sent = {
+            ...target,
+            status: "SENT",
+            attemptedAt,
+            sentAt: new Date().toISOString(),
+            error: undefined
+        };
+        await persist(root, sent);
+        await trace(root, "operation.callback.sent", {
+            operationId: operation.id,
+            operationStatus: operation.status,
+            agentId: target.agentId,
+            transport: result.transport,
+            resultPath: resultPath(operation) ?? ""
+        });
+        return sent;
+    }
+    catch (error) {
+        const failed = {
+            ...target,
+            status: "FAILED",
+            attemptedAt,
+            failedAt: new Date().toISOString(),
+            error: error instanceof Error ? error.message : String(error)
+        };
+        await persist(root, failed);
+        await trace(root, "operation.callback.failed", {
+            operationId: operation.id,
+            operationStatus: operation.status,
+            agentId: target.agentId,
+            error: failed.error ?? "unknown"
+        });
+        return failed;
+    }
+}
+export function completionPrompt(operation) {
+    const artifact = resultPath(operation);
+    const result = operation.result ? JSON.stringify(operation.result) : "{}";
+    return [
+        "[AEH_OPERATION_COMPLETED]",
+        `Detached AEH operation ${operation.id} (${operation.kind}) reached terminal state ${operation.status}.`,
+        "This is an internal AEH controller completion callback for the user request that launched this operation; it is not a new user task.",
+        "Do not start a duplicate AUDIT/RUN and do not restart the completed operation.",
+        `Use aeh_operation_status for ${operation.id} only if you need to refresh durable metadata.${artifact ? ` Read the authoritative artifact ${artifact}.` : ""}`,
+        "Continue and finish the original pending user-facing request now, using the durable operation result and artifacts as the source of truth.",
+        operation.error ? `Operation error: ${operation.error.split("\n", 1)[0]}` : `Operation result: ${result}`
+    ].join("\n");
+}
+function resultPath(operation) {
+    const report = operation.result?.report;
+    return typeof report === "string" && report.trim() ? report.trim() : undefined;
+}
+async function persist(root, target) {
+    const file = operationCompletionFile(root, target.operationId);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temp, `${JSON.stringify(target, null, 2)}\n`);
+    try {
+        await fs.rename(temp, file);
+    }
+    finally {
+        await fs.rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+function requiredId(value, name) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${name} is required.`);
+    return trimmed;
+}
+function safeId(value) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value))
+        throw new Error(`Invalid operation id '${value}'.`);
+    return value;
+}
+function isMissing(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=completion.js.map

package/dist/operations/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/operations/completion.ts"],"names":[],"mappings":"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"}

package/dist/operations/controller.d.ts

@@ -6,10 +6,13 @@ export interface StartOperationOptions {
     nodeExecutable: string;
     entryFile: string;
     spawnProcess?: typeof spawn;
+    completionAgentId?: string;
+    completionSource?: string;
 }
 export interface OperationControllerDeps {
     run?: typeof runProcess;
     trace?: typeof recordPaseoTrace;
+    notifyCompletion?: (root: string, operation: OperationRecord) => Promise<unknown>;
 }
 export declare function startDetachedOperation(root: string, kind: OperationKind, payload: OperationPayload, options: StartOperationOptions): Promise<OperationRecord>;
 export declare function executeOperation(root: string, operationId: string, deps?: OperationControllerDeps): Promise<OperationRecord>;

package/dist/operations/controller.js

@@ -8,7 +8,8 @@ import { runTask } from "../core/run.js";
 import { listManagedPaseoAgents } from "../paseo/runtime.js";
 import { recordPaseoTrace } from "../paseo/trace.js";
 import { runProcess } from "../utils/process.js";
-import { loadOperation, patchOperation, saveOperation } from "./state.js";
+import { disableOperationCompletionTarget, notifyOperationCompletion, registerOperationCompletionTarget } from "./completion.js";
+import { loadOperation, patchOperation, saveOperation, transitionOperationToTerminal } from "./state.js";
 export async function startDetachedOperation(root, kind, payload, options) {
     const absoluteRoot = path.resolve(root);
     const now = new Date().toISOString();
@@ -25,6 +26,10 @@ export async function startDetachedOperation(root, kind, payload, options) {
         updatedAt: now
     };
     await saveOperation(absoluteRoot, record);
+    const completionAgentId = options.completionAgentId?.trim() || process.env.PASEO_AGENT_ID?.trim() || undefined;
+    if (completionAgentId) {
+        await registerOperationCompletionTarget(absoluteRoot, id, completionAgentId, options.completionSource ?? (options.completionAgentId ? "explicit" : "environment"));
+    }
     const spawnProcess = options.spawnProcess ?? spawn;
     let child;
     try {
@@ -40,6 +45,9 @@ export async function startDetachedOperation(root, kind, payload, options) {
         });
     }
     catch (error) {
+        if (completionAgentId) {
+            await disableOperationCompletionTarget(absoluteRoot, id, `Detached controller spawn failed before the initiating tool returned: ${String(error)}`).catch(() => undefined);
+        }
         return patchOperation(absoluteRoot, id, {
             status: "FAILED",
             phase: "spawn-failed",
@@ -92,7 +100,7 @@ export async function executeOperation(root, operationId, deps = {}) {
             const current = await loadOperation(absoluteRoot, operationId);
             if (current.status === "CANCELLED")
                 return current;
-            return patchOperation(absoluteRoot, operationId, {
+            return terminalizeOperation(absoluteRoot, operationId, {
                 status: "SUCCEEDED",
                 phase: "finished",
                 finishedAt: new Date().toISOString(),
@@ -102,7 +110,7 @@ export async function executeOperation(root, operationId, deps = {}) {
                     productionSafe: report.productionSafe,
                     report: `.harness/audits/${report.auditId}.json`
                 }
-            });
+            }, deps);
         }
         const payload = record.payload;
         const contract = await loadTaskContract(absoluteRoot, payload.taskId, config);
@@ -112,7 +120,7 @@ export async function executeOperation(root, operationId, deps = {}) {
         const current = await loadOperation(absoluteRoot, operationId);
         if (current.status === "CANCELLED")
             return current;
-        return patchOperation(absoluteRoot, operationId, {
+        return terminalizeOperation(absoluteRoot, operationId, {
             status: result.status === "PASS" ? "SUCCEEDED" : "FAILED",
             phase: "finished",
             finishedAt: new Date().toISOString(),
@@ -121,18 +129,18 @@ export async function executeOperation(root, operationId, deps = {}) {
                 status: result.status,
                 attempts: result.attempts
             }
-        });
+        }, deps);
     }
     catch (error) {
         const current = await loadOperation(absoluteRoot, operationId).catch(() => record);
         if (current.status === "CANCELLED")
             return current;
-        return patchOperation(absoluteRoot, operationId, {
+        return terminalizeOperation(absoluteRoot, operationId, {
             status: "FAILED",
             phase: "failed",
             error: error instanceof Error ? error.stack ?? error.message : String(error),
             finishedAt: new Date().toISOString()
-        });
+        }, deps);
     }
 }
 export async function waitForOperation(root, operationId, timeoutMs = 1_800_000, pollMs = 500) {
@@ -218,12 +226,12 @@ export async function cancelOperation(root, operationId, deps = {}) {
             cleanupWarnings.push(`agent ${agentId}: ${stopped.stderr || stopped.stdout || `exit ${stopped.exitCode}`}`);
         }
     }
-    return patchOperation(absoluteRoot, operationId, {
+    return terminalizeOperation(absoluteRoot, operationId, {
         status: "CANCELLED",
         phase: "cancelled",
         finishedAt: new Date().toISOString(),
         cleanupWarnings: cleanupWarnings.length ? cleanupWarnings : undefined
-    });
+    }, deps);
 }
 export function createOperationId(kind, seed) {
     const stamp = new Date()
@@ -233,6 +241,27 @@ export function createOperationId(kind, seed) {
     const hash = crypto.createHash("sha256").update(seed).digest("hex").slice(0, 8);
     return `${kind.toUpperCase()}-${stamp}-${hash}`;
 }
+async function terminalizeOperation(root, operationId, patch, deps) {
+    const { record: terminal, transitioned } = await transitionOperationToTerminal(root, operationId, patch);
+    if (!transitioned)
+        return terminal;
+    const trace = deps.trace ?? recordPaseoTrace;
+    try {
+        if (deps.notifyCompletion)
+            await deps.notifyCompletion(root, terminal);
+        else
+            await notifyOperationCompletion(root, terminal, { trace });
+    }
+    catch (error) {
+        await trace(root, "operation.callback.failed", {
+            operationId,
+            operationStatus: terminal.status,
+            error: error instanceof Error ? error.message : String(error),
+            boundary: "controller"
+        }).catch(() => undefined);
+    }
+    return terminal;
+}
 async function ensureOperationWorkspace(root, record, run, trace) {
     const title = `AEH ${record.kind.toUpperCase()} · ${record.id}`;
     const command = `paseo workspace create --isolation local --path ${quote(root)} --title ${quote(title)} --json`;