@useorgx/openclaw-plugin 0.7.6 → 0.7.11

package/dist/http/helpers/auto-continue-engine.js

@@ -9,10 +9,11 @@ import { appendTeamCompletion } from "../../team-context-store.js";
 import { readOpenClawGatewayPort, readOpenClawSettingsSnapshot, } from "../../openclaw-settings.js";
 import { resolveRuntimeHookToken, } from "../../runtime-instance-store.js";
 import { detectMcpHandshakeFailure, shouldKillWorker } from "../../worker-supervisor.js";
+import { humanizeSliceFailure, humanizeSliceFailureSummary } from "./humanize-slice-failure.js";
 import { getOrgxPluginConfigDir } from "../../paths.js";
 import { buildMissionControlGraph, DEFAULT_TOKEN_BUDGET_ASSUMPTIONS, dedupeStrings, detectBehaviorConfigDrift, deriveBehaviorAutomationLevel, deriveBehaviorConfigContext, deriveExecutionPolicy, evaluateScopeCompletion, isDispatchableWorkstreamStatus, isDoneStatus, isTodoStatus, readBudgetEnvNumber, selectSliceTasksByScope, SLICE_SCOPE_TIMEOUT_MULTIPLIER, spawnGuardIsRateLimited, summarizeSpawnGuardBlockReason, } from "./mission-control.js";
 import { createAutopilotRuntime } from "./autopilot-runtime.js";
-import { buildScopeDirective, buildSliceOutputInstructions, buildWorkstreamSlicePrompt, createCodexBinResolver, ensureAutopilotSliceSchemaPath, fileUpdatedAtEpochMs, parseSliceResult, readFileTailSafe, readSliceOutputFile, } from "./autopilot-slice-utils.js";
+import { buildScopeDirective, buildSliceOutputInstructions, buildWorkstreamSlicePrompt, createCodexBinResolver, ensureAutopilotSliceSchemaPath, extractSessionIdFromLog, extractSessionIdFromOutput, fileUpdatedAtEpochMs, parseSliceResult, readFileTailSafe, readSliceOutputFile, } from "./autopilot-slice-utils.js";
 import { pickString } from "./value-utils.js";
 function resolveAutopilotDefaultCwd(filename) {
     let cursor = dirname(filename);
@@ -63,6 +64,35 @@ export function createAutoContinueEngine(deps) {
         ? "reject"
         : "approve";
     const autoContinueSliceRuns = new Map();
+    const workstreamSessionStore = new Map();
+    function sessionResumeEnabled() {
+        const raw = (process.env.ORGX_AUTOPILOT_SESSION_RESUME ?? "").trim().toLowerCase();
+        if (!raw)
+            return false;
+        return !(raw === "0" || raw === "false" || raw === "no" || raw === "off");
+    }
+    function setWorkstreamSession(workstreamId, entry) {
+        workstreamSessionStore.set(workstreamId, entry);
+    }
+    function getWorkstreamSession(workstreamId) {
+        return workstreamSessionStore.get(workstreamId) ?? null;
+    }
+    function clearWorkstreamSession(initiativeId) {
+        for (const [key, entry] of workstreamSessionStore.entries()) {
+            if (entry.initiativeId === initiativeId) {
+                workstreamSessionStore.delete(key);
+            }
+        }
+    }
+    function listWorkstreamSessions(initiativeId) {
+        const results = [];
+        for (const entry of workstreamSessionStore.values()) {
+            if (!initiativeId || entry.initiativeId === initiativeId) {
+                results.push(entry);
+            }
+        }
+        return results;
+    }
     /** Spread into any metadata object to flag mock-worker activity. */
     function mockMeta(slice) {
         return slice.isMockWorker ? { mock: true } : {};
@@ -1700,8 +1730,8 @@ export function createAutoContinueEngine(deps) {
                             const decisionResult = await requestDecisionQueued({
                                 initiativeId: run.initiativeId,
                                 correlationId: slice.runId,
-                                title: `Autopilot slice MCP failed: ${slice.workstreamTitle ?? slice.workstreamId}`,
-                                summary: `MCP handshake failed${mcpHandshake.server ? ` for ${mcpHandshake.server}` : ""}. Review logs/output and decide whether to retry or pause autopilot.`,
+                                title: `Agent couldn't connect to tools: ${slice.workstreamTitle ?? slice.workstreamId}`,
+                                summary: humanizeSliceFailureSummary(`MCP handshake failed${mcpHandshake.server ? ` for ${mcpHandshake.server}` : ""}.`),
                                 urgency: "high",
                                 options: [
                                     "Retry this workstream slice",
@@ -1819,8 +1849,8 @@ export function createAutoContinueEngine(deps) {
                             const decisionResult = await requestDecisionQueued({
                                 initiativeId: run.initiativeId,
                                 correlationId: slice.runId,
-                                title: `Autopilot slice ${humanLabel}: ${slice.workstreamTitle ?? slice.workstreamId}`,
-                                summary: "The slice was terminated because it stopped making progress. Review logs/output and decide whether to retry or pause autopilot.",
+                                title: `Agent ${humanLabel === "timed out" ? "ran out of time" : "stopped making progress"}: ${slice.workstreamTitle ?? slice.workstreamId}`,
+                                summary: humanizeSliceFailureSummary(slice.lastError ?? `Autopilot slice ${humanLabel}`),
                                 urgency: "high",
                                 options: [
                                     "Retry this workstream slice",
@@ -1904,6 +1934,25 @@ export function createAutoContinueEngine(deps) {
                 const raw = readSliceOutputFile(slice.outputPath);
                 const parsed = raw ? parseSliceResult(raw) : null;
                 const parsedStatus = parsed?.status ?? "error";
+                // Session capture: extract CLI session ID from output or log for future resume.
+                if (sessionResumeEnabled()) {
+                    const outputSessionId = raw ? extractSessionIdFromOutput(raw, slice.sourceClient) : null;
+                    const logSessionId = outputSessionId
+                        ? null
+                        : extractSessionIdFromLog(readFileTailSafe(slice.logPath, 32_000), slice.sourceClient);
+                    const capturedSessionId = outputSessionId ?? logSessionId ?? null;
+                    if (capturedSessionId) {
+                        slice.cliSessionId = capturedSessionId;
+                        setWorkstreamSession(slice.workstreamId, {
+                            sessionId: capturedSessionId,
+                            workstreamId: slice.workstreamId,
+                            initiativeId: slice.initiativeId,
+                            sourceClient: slice.sourceClient,
+                            capturedAt: new Date().toISOString(),
+                            fromRunId: slice.runId,
+                        });
+                    }
+                }
                 const defaultDecisionBlocking = parsedStatus === "completed" ? false : true;
                 const allDecisions = Array.isArray(parsed?.decisions_needed)
                     ? (parsed?.decisions_needed ?? [])
@@ -2335,17 +2384,18 @@ export function createAutoContinueEngine(deps) {
                     };
                     if (!blockingDecisionQueued) {
                         const blockedLike = slice.status === "blocked";
+                        const fallbackRawError = parsed?.summary ?? slice.lastError ??
+                            (blockedLike
+                                ? "Execution is blocked and needs intervention."
+                                : "Agent process exited without a valid output contract.");
+                        const fallbackHumanized = humanizeSliceFailure(fallbackRawError);
                         fallbackDecisionResult = await requestDecisionQueued({
                             initiativeId: run.initiativeId,
                             correlationId: slice.runId,
                             title: blockedLike
-                                ? `Autopilot slice blocked: ${slice.workstreamTitle ?? slice.workstreamId}`
-                                : `Autopilot slice failed: ${slice.workstreamTitle ?? slice.workstreamId}`,
-                            summary: parsed?.summary ??
-                                slice.lastError ??
-                                (blockedLike
-                                    ? "The slice reported a blocked/decision-required state without a blocking decision payload. Review logs/output and decide whether to retry, unblock, or skip."
-                                    : "The slice failed without producing a valid output contract. Review logs/output and decide whether to retry or pause autopilot."),
+                                ? `Agent needs your help: ${slice.workstreamTitle ?? slice.workstreamId}`
+                                : `${fallbackHumanized.headline}: ${slice.workstreamTitle ?? slice.workstreamId}`,
+                            summary: fallbackHumanized.explanation,
                             urgency: "high",
                             options: [
                                 "Retry this workstream slice",
@@ -2421,12 +2471,14 @@ export function createAutoContinueEngine(deps) {
                     decisions.length === 0 &&
                     statusUpdateResult.applied === 0;
                 if (!parsed || parsedStatus === "error" || completionHadNoOutcome) {
+                    const rawError = slice.lastError ?? (completionHadNoOutcome
+                        ? "Completed without verifiable outcomes or artifacts."
+                        : "Agent process exited without a valid output contract.");
+                    const humanized = humanizeSliceFailure(rawError);
                     const attentionTitle = completionHadNoOutcome
-                        ? `Autopilot slice needs verification: ${slice.workstreamTitle ?? slice.workstreamId}`
-                        : `Autopilot slice failed: ${slice.workstreamTitle ?? slice.workstreamId}`;
-                    const attentionSummary = completionHadNoOutcome
-                        ? "The slice reported completion but did not produce artifacts or status updates. Decide whether to retry, request stronger output, or mark tasks manually."
-                        : "The slice exited without a valid output contract. Review logs/output and decide whether to retry or pause autopilot.";
+                        ? `Agent finished but produced nothing: ${slice.workstreamTitle ?? slice.workstreamId}`
+                        : `${humanized.headline}: ${slice.workstreamTitle ?? slice.workstreamId}`;
+                    const attentionSummary = humanized.explanation;
                     const decisionResult = await requestDecisionQueued({
                         initiativeId: run.initiativeId,
                         correlationId: slice.runId,
@@ -3463,6 +3515,9 @@ export function createAutoContinueEngine(deps) {
         catch {
             // best effort
         }
+        // Session resume: check if a previous session exists for this workstream.
+        const priorSession = sessionResumeEnabled() ? getWorkstreamSession(selectedWorkstreamId) : null;
+        const resumedFromSessionId = priorSession?.sessionId ?? null;
         const spawned = spawnCodexSliceWorker({
             runId: sliceRunId,
             prompt,
@@ -3470,6 +3525,7 @@ export function createAutoContinueEngine(deps) {
             logPath,
             outputPath,
             outputSchemaPath: schemaPath,
+            resumeSessionId: resumedFromSessionId,
             env: {
                 ORGX_SOURCE_CLIENT: executorSourceClient,
                 ORGX_RUN_ID: sliceRunId,
@@ -3523,6 +3579,8 @@ export function createAutoContinueEngine(deps) {
             scopeMilestoneIds: scopeMilestoneIds,
             lastError: null,
             isMockWorker: workerKind === "mock",
+            cliSessionId: null,
+            resumedFromSessionId,
         };
         autoContinueSliceRuns.set(sliceRunId, slice);
         try {
@@ -4094,6 +4152,7 @@ export function createAutoContinueEngine(deps) {
             run.activeTaskId = null;
             run.activeRunId = null;
             run.activeTaskTokenEstimate = null;
+            clearWorkstreamSession(input.initiativeId);
         }
         syncLegacyRunPointers(run);
         autoContinueRuns.set(input.initiativeId, run);
@@ -4191,5 +4250,12 @@ export function createAutoContinueEngine(deps) {
         getAutoContinueLaneForWorkstream,
         scheduleAutoFixForWorkstream,
         startAutoContinueRun,
+        // Session store (for resume support)
+        workstreamSessionStore,
+        getWorkstreamSession,
+        setWorkstreamSession,
+        clearWorkstreamSession,
+        listWorkstreamSessions,
+        sessionResumeEnabled,
     };
 }

package/dist/http/helpers/autopilot-runtime.d.ts

@@ -21,6 +21,7 @@ export declare function createAutopilotRuntime(deps: CreateAutopilotRuntimeDeps)
         outputPath: string;
         outputSchemaPath?: string;
         env: Record<string, string | undefined>;
+        resumeSessionId?: string | null;
     }) => {
         pid: number | null;
     };

package/dist/http/helpers/autopilot-runtime.js

@@ -190,6 +190,12 @@ export function createAutopilotRuntime(deps) {
             return false;
         }
     }
+    function sessionResumeEnabled() {
+        const raw = (process.env.ORGX_AUTOPILOT_SESSION_RESUME ?? "").trim().toLowerCase();
+        if (!raw)
+            return false;
+        return !(raw === "0" || raw === "false" || raw === "no" || raw === "off");
+    }
     function spawnCodexSliceWorker(input) {
         ensurePrivateDirForFile(input.logPath);
         ensurePrivateDirForFile(input.outputPath);
@@ -335,8 +341,15 @@ export function createAutopilotRuntime(deps) {
                 claudeExtraArgs.push("--print");
             if (!hasOutputFormat)
                 claudeExtraArgs.push("--output-format", "json");
-            if (!hasNoSessionPersistence)
+            // Session resume: when resumeSessionId is provided, use --resume and skip --no-session-persistence.
+            // When feature is enabled but no resume, omit --no-session-persistence to persist for future resume.
+            const resumeId = typeof input.resumeSessionId === "string" ? input.resumeSessionId.trim() : "";
+            if (resumeId) {
+                claudeExtraArgs.push("--resume", resumeId);
+            }
+            else if (!sessionResumeEnabled() && !hasNoSessionPersistence) {
                 claudeExtraArgs.push("--no-session-persistence");
+            }
             if (!hasPermissionMode)
                 claudeExtraArgs.push("--permission-mode", "bypassPermissions");
             if (!hasDangerousSkipPermissions && !hasAllowDangerousSkipPermissions) {
@@ -469,10 +482,25 @@ export function createAutopilotRuntime(deps) {
         }
         const codexInfo = deps.resolveCodexBinInfo();
         const codexBin = codexInfo.bin;
-        const rawArgs = (process.env.ORGX_CODEX_ARGS ?? "").trim();
+        const codexResumeId = typeof input.resumeSessionId === "string" ? input.resumeSessionId.trim() : "";
+        // Session resume: use "resume <id>" subcommand instead of "exec --ephemeral"
+        // When feature enabled but no resume ID: omit --ephemeral to persist for future resume
+        let rawArgs;
+        let defaultArgs;
+        if (codexResumeId) {
+            rawArgs = "";
+            defaultArgs = ["resume", codexResumeId, "--full-auto", "--skip-git-repo-check"];
+        }
+        else {
+            rawArgs = (process.env.ORGX_CODEX_ARGS ?? "").trim();
+            const featureEnabled = sessionResumeEnabled();
+            defaultArgs = featureEnabled
+                ? ["exec", "--full-auto", "--skip-git-repo-check"]
+                : ["exec", "--ephemeral", "--full-auto", "--skip-git-repo-check"];
+        }
         const normalizedArgs = normalizeCodexArgs(rawArgs.length > 0
             ? rawArgs.split(/\s+/).filter(Boolean)
-            : ["exec", "--ephemeral", "--full-auto", "--skip-git-repo-check"]);
+            : defaultArgs);
         const args = hasExplicitCodexSubcommand(normalizedArgs)
             ? normalizedArgs
             : ["exec", ...normalizedArgs];

package/dist/http/helpers/autopilot-slice-utils.d.ts

@@ -2,6 +2,16 @@ export declare function ensureAutopilotSliceSchemaPath(schemaFilename: string):
 export declare function parseSliceResult<T extends object>(raw: string): T | null;
 export declare function readSliceOutputFile(pathname: string): string | null;
 export declare function readFileTailSafe(pathname: string, maxChars?: number): string;
+/**
+ * Extract a CLI session ID from structured output JSON (Claude/Codex envelope).
+ * Looks for `session_id`, `sessionId`, or `conversation_id` fields.
+ */
+export declare function extractSessionIdFromOutput(raw: string, _sourceClient?: string): string | null;
+/**
+ * Extract a CLI session ID from worker log text.
+ * Matches patterns emitted by Claude Code and Codex CLIs.
+ */
+export declare function extractSessionIdFromLog(logContent: string, _sourceClient?: string): string | null;
 export declare function fileUpdatedAtEpochMs(pathname: string, fallbackEpochMs: number): number;
 export type CodexBinInfo = {
     bin: string;

package/dist/http/helpers/autopilot-slice-utils.js

@@ -470,6 +470,64 @@ export function readFileTailSafe(pathname, maxChars = 64_000) {
         return "";
     }
 }
+// ---------------------------------------------------------------------------
+// Session ID extraction (for session resume support)
+// ---------------------------------------------------------------------------
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/**
+ * Extract a CLI session ID from structured output JSON (Claude/Codex envelope).
+ * Looks for `session_id`, `sessionId`, or `conversation_id` fields.
+ */
+export function extractSessionIdFromOutput(raw, _sourceClient) {
+    if (!raw || typeof raw !== "string")
+        return null;
+    const parsed = parseJsonSafe(raw.trim());
+    if (parsed && typeof parsed === "object") {
+        // Walk common envelope shapes: top-level, result, structured_output, final_output
+        const candidates = [
+            parsed,
+            parsed.result,
+            parsed.structured_output,
+            parsed.final_output,
+        ];
+        for (const obj of candidates) {
+            if (!obj || typeof obj !== "object")
+                continue;
+            const record = obj;
+            for (const key of ["session_id", "sessionId", "conversation_id"]) {
+                const value = record[key];
+                if (typeof value === "string" && UUID_RE.test(value))
+                    return value.trim();
+            }
+        }
+    }
+    // Fallback: scan raw text for session_id: <uuid> pattern
+    const inline = raw.match(/session_id\s*[:=]\s*"?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"?/i);
+    if (inline && typeof inline[1] === "string")
+        return inline[1];
+    return null;
+}
+/**
+ * Extract a CLI session ID from worker log text.
+ * Matches patterns emitted by Claude Code and Codex CLIs.
+ */
+export function extractSessionIdFromLog(logContent, _sourceClient) {
+    if (!logContent || typeof logContent !== "string")
+        return null;
+    // Claude Code: "Resume this session with: claude --resume <uuid>"
+    const claudeResume = logContent.match(/claude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    if (claudeResume && typeof claudeResume[1] === "string")
+        return claudeResume[1];
+    // Codex: "codex resume <uuid>"
+    const codexResume = logContent.match(/codex\s+resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    if (codexResume && typeof codexResume[1] === "string")
+        return codexResume[1];
+    // Generic: "Session: <uuid>", "session_id: <uuid>", "saving session <uuid>"
+    const generic = logContent.match(/(?:Session|session_id|saving\s+session)\s*[:=]?\s*([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    if (generic && typeof generic[1] === "string")
+        return generic[1];
+    return null;
+}
 export function fileUpdatedAtEpochMs(pathname, fallbackEpochMs) {
     try {
         const st = statSync(pathname);

package/dist/http/helpers/humanize-slice-failure.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Translates raw auto-continue engine error strings into human-readable
+ * decision context suitable for operator display.
+ *
+ * Used at decision creation time to enrich the `summary` field and
+ * generate structured options when the engine produces terse diagnostics.
+ */
+export interface HumanizedSliceFailure {
+    /** One-line human headline, e.g. "Agent work stopped unexpectedly" */
+    headline: string;
+    /** Multi-sentence explanation for operators */
+    explanation: string;
+    /** Parsed structured data extracted from the raw string */
+    structuredDetails: {
+        exitCode?: string;
+        signal?: string;
+        elapsedMs?: string;
+        idleMs?: string;
+        server?: string;
+        reason?: string;
+    };
+    /** Severity for UI theming */
+    severity: "critical" | "warning" | "info";
+}
+/**
+ * Translate a raw auto-continue error/context string into a human-friendly
+ * decision description. Falls back gracefully for unrecognised patterns.
+ */
+export declare function humanizeSliceFailure(raw: string): HumanizedSliceFailure;
+/**
+ * Generate a human-friendly summary string from a raw error, suitable for
+ * the `summary` field when creating decisions. Combines the headline and
+ * explanation into a concise paragraph.
+ */
+export declare function humanizeSliceFailureSummary(raw: string): string;

package/dist/http/helpers/humanize-slice-failure.js

@@ -0,0 +1,137 @@
+/**
+ * Translates raw auto-continue engine error strings into human-readable
+ * decision context suitable for operator display.
+ *
+ * Used at decision creation time to enrich the `summary` field and
+ * generate structured options when the engine produces terse diagnostics.
+ */
+const PATTERNS = [
+    {
+        test: /Worker exited without structured output.*?code=(\S+?),\s*signal=(\S+?)\)/i,
+        headline: "Agent work stopped unexpectedly",
+        explain: (_raw, m) => {
+            const code = m[1] === "null" ? "none" : m[1];
+            const signal = m[2] === "null" ? "none" : m[2];
+            const parts = [
+                "The agent process exited before producing results.",
+            ];
+            if (signal !== "none" && signal !== "null") {
+                parts.push(`It was terminated by signal ${signal}, which usually means the worker was stopped externally or ran out of resources.`);
+            }
+            else {
+                parts.push("This usually means the worker crashed or was terminated before completing.");
+            }
+            parts.push(`Exit code: ${code}. Signal: ${signal}.`);
+            return parts.join(" ");
+        },
+        severity: "critical",
+        extractDetails: (_raw, m) => ({
+            exitCode: m[1] === "null" ? undefined : m[1],
+            signal: m[2] === "null" ? undefined : m[2],
+        }),
+    },
+    {
+        test: /MCP handshake failed(?:\s+for\s+(\S+))?/i,
+        headline: "Agent couldn't connect to tools",
+        explain: (_raw, m) => {
+            const server = m[1] ? ` (${m[1]})` : "";
+            return `The agent failed to establish a connection with its tool server${server}. This typically means the MCP server is unreachable, misconfigured, or took too long to respond. Retrying often resolves transient connection issues.`;
+        },
+        severity: "critical",
+        extractDetails: (_raw, m) => ({
+            server: m[1] || undefined,
+        }),
+    },
+    {
+        test: /(?:Slice|Autopilot slice) timed out after (\d+)/i,
+        headline: "Agent ran out of time",
+        explain: (_raw, m) => {
+            const ms = parseInt(m[1], 10);
+            const mins = Math.round(ms / 60_000);
+            return `The agent exceeded its ${mins > 0 ? `${mins}-minute` : `${ms}ms`} time limit without completing. This can happen when the task is too large for a single work slice or when the agent is waiting on a slow external resource. Consider breaking the work into smaller steps or increasing the time budget.`;
+        },
+        severity: "warning",
+        extractDetails: (_raw, m) => ({
+            elapsedMs: m[1],
+        }),
+    },
+    {
+        test: /(?:Slice|Autopilot slice) stalled.*?(?:no progress for (\d+))?/i,
+        headline: "Agent stopped making progress",
+        explain: (_raw, m) => {
+            const mins = m[1] ? Math.round(parseInt(m[1], 10) / 60_000) : null;
+            const duration = mins ? ` for ${mins} minute${mins !== 1 ? "s" : ""}` : "";
+            return `The agent stopped producing output${duration}. This can indicate it's stuck in a loop, waiting on an unresponsive resource, or unable to proceed with the current approach. Reviewing the session logs may reveal the specific bottleneck.`;
+        },
+        severity: "warning",
+        extractDetails: (_raw, m) => ({
+            idleMs: m[1] || undefined,
+        }),
+    },
+    {
+        test: /blocked.*?(?:needs|requires?) intervention/i,
+        headline: "Agent needs your help to continue",
+        explain: () => "The agent reached a point where it cannot proceed without human guidance. This may be a question about requirements, a permission needed, or an ambiguity that needs resolution.",
+        severity: "warning",
+    },
+    {
+        test: /blocked.*?without.*?(?:blocking )?decision payload/i,
+        headline: "Agent paused without clear reason",
+        explain: () => "The agent reported it was blocked but did not specify what decision is needed. Review the session logs for context about what the agent was working on when it paused.",
+        severity: "warning",
+    },
+    {
+        test: /code=(\d+)/i,
+        headline: "Agent encountered an error",
+        explain: (_raw, m) => `The agent process exited with error code ${m[1]}. This indicates the agent hit an unexpected condition during execution. Reviewing the session logs will show what operation failed.`,
+        severity: "critical",
+        extractDetails: (_raw, m) => ({
+            exitCode: m[1],
+        }),
+    },
+    {
+        test: /completed.*?(?:without|no) (?:verifiable )?(?:outcomes?|artifacts?|status updates?)/i,
+        headline: "Agent finished but produced nothing",
+        explain: () => "The agent reported completion but did not produce any artifacts, status updates, or measurable outcomes. This may mean the work was done informally (e.g., analysis without a written output) or the agent couldn't find actionable work.",
+        severity: "info",
+    },
+    {
+        test: /Spawn guard denied/i,
+        headline: "Agent dispatch was blocked by safety check",
+        explain: (_raw) => "The system's safety checks prevented this agent from starting. This is typically due to capacity limits, domain restrictions, or quality gate requirements that haven't been met.",
+        severity: "warning",
+    },
+];
+/**
+ * Translate a raw auto-continue error/context string into a human-friendly
+ * decision description. Falls back gracefully for unrecognised patterns.
+ */
+export function humanizeSliceFailure(raw) {
+    for (const pattern of PATTERNS) {
+        const match = raw.match(pattern.test);
+        if (match) {
+            return {
+                headline: pattern.headline,
+                explanation: pattern.explain(raw, match),
+                structuredDetails: pattern.extractDetails?.(raw, match) ?? {},
+                severity: pattern.severity,
+            };
+        }
+    }
+    // Fallback for unrecognised patterns
+    return {
+        headline: "Agent work needs attention",
+        explanation: raw,
+        structuredDetails: {},
+        severity: "warning",
+    };
+}
+/**
+ * Generate a human-friendly summary string from a raw error, suitable for
+ * the `summary` field when creating decisions. Combines the headline and
+ * explanation into a concise paragraph.
+ */
+export function humanizeSliceFailureSummary(raw) {
+    const h = humanizeSliceFailure(raw);
+    return `${h.headline}. ${h.explanation}`;
+}

package/dist/http/helpers/mission-control.d.ts

@@ -71,6 +71,7 @@ export interface MissionControlExecutionPolicy {
 export declare const SLICE_SCOPE_MAX_TASKS: Record<SliceScope, number>;
 export declare const SLICE_SCOPE_TIMEOUT_MULTIPLIER: Record<SliceScope, number>;
 export declare const ORGX_SKILL_BY_DOMAIN: Record<string, string>;
+export declare function safeErrorMessage(err: unknown): string;
 interface BudgetEnvBounds {
     min?: number;
     max?: number;

package/dist/http/helpers/mission-control.js

@@ -1,4 +1,5 @@
 import { pickNumber, pickString, toIsoString } from "./value-utils.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const SLICE_SCOPE_MAX_TASKS = {
     task: 6,
     milestone: 15,
@@ -18,11 +19,74 @@ export const ORGX_SKILL_BY_DOMAIN = {
     design: "orgx-design-agent",
     orchestration: "orgx-orchestrator-agent",
 };
-function safeErrorMessage(err) {
-    if (err instanceof Error)
-        return err.message;
-    if (typeof err === "string")
-        return err;
+export function safeErrorMessage(err) {
+    const raw = err instanceof Error
+        ? err.message
+        : typeof err === "string"
+            ? err
+            : err && typeof err === "object" && "message" in err && typeof err.message === "string"
+                ? (err.message ?? "")
+                : "";
+    const parseStructuredMessage = (value) => {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        const parseObjectMessage = (parsed) => {
+            if (!parsed || typeof parsed !== "object")
+                return null;
+            const root = parsed;
+            const nested = root.error && typeof root.error === "object" ? root.error : null;
+            const envelope = nested ?? root;
+            return ((typeof envelope.message === "string" && envelope.message.trim()) ||
+                (typeof envelope.detail === "string" && envelope.detail.trim()) ||
+                (!nested && typeof root.error === "string" && root.error.trim()) ||
+                null);
+        };
+        try {
+            const parsed = JSON.parse(trimmed);
+            const direct = parseObjectMessage(parsed);
+            if (direct)
+                return direct;
+        }
+        catch {
+            // fall through and attempt extraction of embedded JSON blocks
+        }
+        const firstBrace = trimmed.indexOf("{");
+        const lastBrace = trimmed.lastIndexOf("}");
+        if (firstBrace >= 0 && lastBrace > firstBrace) {
+            const candidate = trimmed.slice(firstBrace, lastBrace + 1);
+            try {
+                const parsed = JSON.parse(candidate);
+                return parseObjectMessage(parsed);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    };
+    const stripStructuredNoise = (value) => value
+        .replace(/"requestId"\s*:\s*"[^"]*"/gi, "")
+        .replace(/"timestamp"\s*:\s*"[^"]*"/gi, "")
+        .replace(/"docsUrl"\s*:\s*"[^"]*"/gi, "")
+        .replace(/\brequest[_\s-]?id[:=]\s*[\w-]+/gi, "")
+        .replace(/\btimestamp[:=]\s*\S+/gi, "")
+        .replace(/\bdocsUrl[:=]\s*\S+/gi, "")
+        .replace(/[{}]/g, " ")
+        .replace(/\s{2,}/g, " ")
+        .trim();
+    const normalizedMessage = parseStructuredMessage(raw) ?? raw;
+    const sanitized = stripStructuredNoise(normalizedMessage);
+    const normalized = sanitized.toLowerCase();
+    if (normalized.length > 0) {
+        if (normalized.includes("internal_error") || normalized.includes("internal server error")) {
+            return "temporary server issue";
+        }
+        if (normalized.includes("failed to list decision") || normalized.includes("failed to load decision")) {
+            return "decision data temporarily unavailable";
+        }
+        return sanitized;
+    }
     return "Unexpected error";
 }
 function toNullableBoolean(value) {
@@ -641,6 +705,9 @@ export async function listEntitiesSafe(client, type, filters) {
     }
 }
 export async function buildMissionControlGraph(client, initiativeId, options) {
+    if (!UUID_RE.test(initiativeId)) {
+        throw new Error(`buildMissionControlGraph: initiativeId must be a UUID, got "${initiativeId}"`);
+    }
     const degraded = [];
     const preloadedInitiative = options?.initiativeEntity ?? null;
     const [initiativeResult, workstreamResult, milestoneResult, taskResult] = await Promise.all([