@useorgx/openclaw-plugin 0.7.8 → 0.7.15

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

@@ -159,7 +159,57 @@ export function ensureAutopilotSliceSchemaPath(schemaFilename) {
 }
 export function parseSliceResult(raw) {
     const allowedStatuses = new Set(["completed", "blocked", "needs_decision", "error"]);
+    const normalizeStatusValue = (value) => {
+        if (typeof value !== "string")
+            return "";
+        const normalized = value.trim().toLowerCase();
+        return allowedStatuses.has(normalized) ? normalized : "";
+    };
     const stripUtf8Bom = (text) => text.replace(/^\uFEFF/, "");
+    const extractTopLevelObjects = (text) => {
+        let inString = false;
+        let escaped = false;
+        let depth = 0;
+        let start = -1;
+        const objects = [];
+        for (let i = 0; i < text.length; i += 1) {
+            const ch = text[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                    continue;
+                }
+                if (ch === "\\") {
+                    escaped = true;
+                    continue;
+                }
+                if (ch === "\"") {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === "\"") {
+                inString = true;
+                continue;
+            }
+            if (ch === "{") {
+                if (depth === 0)
+                    start = i;
+                depth += 1;
+                continue;
+            }
+            if (ch === "}") {
+                if (depth <= 0)
+                    continue;
+                depth -= 1;
+                if (depth === 0 && start >= 0) {
+                    objects.push(text.slice(start, i + 1));
+                    start = -1;
+                }
+            }
+        }
+        return objects;
+    };
     const extractMarkdownJsonFences = (text) => {
         const matches = text.matchAll(/```(?:json)?\s*([\s\S]*?)\s*```/gi);
         const fences = [];
@@ -192,13 +242,20 @@ export function parseSliceResult(raw) {
                 return normalizeSliceResult(parsedInner);
             }
         }
+        const objectCandidates = extractTopLevelObjects(normalized);
+        for (let i = objectCandidates.length - 1; i >= 0; i -= 1) {
+            const parsedObject = parseJsonSafe(stripUtf8Bom(objectCandidates[i]));
+            if (parsedObject && typeof parsedObject === "object" && isLikelySliceResult(parsedObject)) {
+                return normalizeSliceResult(parsedObject);
+            }
+        }
         return null;
     };
     const isLikelySliceResult = (value) => {
         if (!value || typeof value !== "object")
             return false;
         const record = value;
-        const status = typeof record.status === "string" ? record.status : "";
+        const status = normalizeStatusValue(record.status);
         const workstreamId = typeof record.workstream_id === "string" ? record.workstream_id : "";
         const summary = typeof record.summary === "string" ? record.summary : "";
         return (allowedStatuses.has(status) &&
@@ -207,10 +264,13 @@ export function parseSliceResult(raw) {
     };
     const normalizeSliceResult = (value) => {
         const record = value;
-        const status = typeof record.status === "string" ? record.status : "";
+        const status = normalizeStatusValue(record.status);
         const decisions = record.decisions_needed;
         let changed = false;
-        let nextRecord = record;
+        let nextRecord = status ? { ...record, status } : record;
+        if (status && record.status !== status) {
+            changed = true;
+        }
         if (Array.isArray(decisions)) {
             const normalized = decisions.map((decision) => {
                 if (!decision || typeof decision !== "object")
@@ -275,7 +335,11 @@ export function parseSliceResult(raw) {
         const record = value;
         const parseEmbeddedText = (candidate) => {
             if (typeof candidate === "string") {
-                return parseSliceJsonText(candidate);
+                const direct = parseSliceJsonText(candidate);
+                if (direct)
+                    return direct;
+                // Some envelopes embed worker logs/prose with a trailing JSON object.
+                return parseSliceResult(candidate);
             }
             if (Array.isArray(candidate)) {
                 for (let i = candidate.length - 1; i >= 0; i -= 1) {
@@ -288,12 +352,6 @@ export function parseSliceResult(raw) {
             if (!candidate || typeof candidate !== "object")
                 return null;
             const candidateRecord = candidate;
-            if (typeof candidateRecord.value === "string") {
-                return parseSliceJsonText(candidateRecord.value);
-            }
-            if (typeof candidateRecord.text === "string") {
-                return parseSliceJsonText(candidateRecord.text);
-            }
             const fromValue = parseEmbeddedText(candidateRecord.value);
             if (fromValue)
                 return fromValue;
@@ -392,50 +450,6 @@ export function parseSliceResult(raw) {
     if (directTextParsed && typeof directTextParsed === "object")
         return directTextParsed;
     // Tolerant parse: extract the last complete top-level JSON object from mixed logs.
-    const extractTopLevelObjects = (text) => {
-        let inString = false;
-        let escaped = false;
-        let depth = 0;
-        let start = -1;
-        const objects = [];
-        for (let i = 0; i < text.length; i += 1) {
-            const ch = text[i];
-            if (inString) {
-                if (escaped) {
-                    escaped = false;
-                    continue;
-                }
-                if (ch === "\\") {
-                    escaped = true;
-                    continue;
-                }
-                if (ch === "\"") {
-                    inString = false;
-                }
-                continue;
-            }
-            if (ch === "\"") {
-                inString = true;
-                continue;
-            }
-            if (ch === "{") {
-                if (depth === 0)
-                    start = i;
-                depth += 1;
-                continue;
-            }
-            if (ch === "}") {
-                if (depth <= 0)
-                    continue;
-                depth -= 1;
-                if (depth === 0 && start >= 0) {
-                    objects.push(text.slice(start, i + 1));
-                    start = -1;
-                }
-            }
-        }
-        return objects;
-    };
     const candidates = extractTopLevelObjects(trimmed);
     for (let i = candidates.length - 1; i >= 0; i -= 1) {
         const candidate = candidates[i];
@@ -470,6 +484,96 @@ 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 extractUuid = (value) => {
+        const match = value.trim().match(UUID_RE);
+        return match?.[0] ?? null;
+    };
+    const findSessionId = (candidate) => {
+        if (!candidate)
+            return null;
+        if (typeof candidate === "string") {
+            const parsedCandidate = parseJsonSafe(candidate.trim());
+            if (parsedCandidate)
+                return findSessionId(parsedCandidate);
+            return null;
+        }
+        if (Array.isArray(candidate)) {
+            for (const item of candidate) {
+                const found = findSessionId(item);
+                if (found)
+                    return found;
+            }
+            return null;
+        }
+        if (typeof candidate !== "object")
+            return null;
+        const record = candidate;
+        for (const key of ["session_id", "sessionId", "conversation_id"]) {
+            const value = record[key];
+            if (typeof value === "string") {
+                const uuid = extractUuid(value);
+                if (uuid)
+                    return uuid;
+            }
+        }
+        return (findSessionId(record.value) ??
+            findSessionId(record.text) ??
+            findSessionId(record.content) ??
+            findSessionId(record.output_text) ??
+            null);
+    };
+    const parsed = parseJsonSafe(raw.trim());
+    if (parsed && typeof parsed === "object") {
+        const found = findSessionId([
+            parsed,
+            parsed.result,
+            parsed.structured_output,
+            parsed.final_output,
+            parsed.output_text,
+            parsed.output,
+        ]);
+        if (found) {
+            return found;
+        }
+    }
+    // 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/hash-utils.d.ts

@@ -1 +1 @@
-export { idempotencyKey, stableHash } from "../../hash-utils.js";
+export { deterministicActivityId, idempotencyKey, stableHash } from "../../hash-utils.js";

package/dist/http/helpers/hash-utils.js

@@ -1 +1 @@
-export { idempotencyKey, stableHash } from "../../hash-utils.js";
+export { deterministicActivityId, idempotencyKey, stableHash } from "../../hash-utils.js";

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

@@ -19,11 +19,77 @@ 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("relation does not exist")) {
+            return sanitized;
+        }
+        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) {
@@ -642,10 +708,10 @@ export async function listEntitiesSafe(client, type, filters) {
     }
 }
 export async function buildMissionControlGraph(client, initiativeId, options) {
+    const degraded = [];
     if (!UUID_RE.test(initiativeId)) {
-        throw new Error(`buildMissionControlGraph: initiativeId must be a UUID, got "${initiativeId}"`);
+        degraded.push(`initiative id "${initiativeId}" is non-UUID; using compatibility graph lookup`);
     }
-    const degraded = [];
     const preloadedInitiative = options?.initiativeEntity ?? null;
     const [initiativeResult, workstreamResult, milestoneResult, taskResult] = await Promise.all([
         preloadedInitiative

package/dist/http/helpers/queue-constants.d.ts

@@ -0,0 +1,37 @@
+/** Queue state for next-up items (workstream-level). */
+export declare const QueueState: {
+    readonly QUEUED: "queued";
+    readonly RUNNING: "running";
+    readonly BLOCKED: "blocked";
+    readonly IDLE: "idle";
+    /** Used only in the API normalization layer (mission-control-read.ts). */
+    readonly COMPLETED: "completed";
+};
+/** Core queue states used by the queue builder (excludes "completed"). */
+export type CoreQueueState = "queued" | "running" | "blocked" | "idle";
+/** Extended queue state including API-only values. */
+export type QueueStateValue = (typeof QueueState)[keyof typeof QueueState];
+/** Auto-continue lane state (per-workstream within a run). */
+export declare const LaneState: {
+    readonly IDLE: "idle";
+    readonly RUNNING: "running";
+    readonly BLOCKED: "blocked";
+    readonly WAITING_DEPENDENCY: "waiting_dependency";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly COMPLETED: "completed";
+};
+export type LaneStateValue = (typeof LaneState)[keyof typeof LaneState];
+/** Auto-continue run status. */
+export declare const RunStatus: {
+    readonly RUNNING: "running";
+    readonly STOPPING: "stopping";
+    readonly STOPPED: "stopped";
+};
+export type RunStatusValue = (typeof RunStatus)[keyof typeof RunStatus];
+/** Runner source — how the agent was assigned. */
+export declare const RunnerSource: {
+    readonly ASSIGNED: "assigned";
+    readonly INFERRED: "inferred";
+    readonly FALLBACK: "fallback";
+};
+export type RunnerSourceValue = (typeof RunnerSource)[keyof typeof RunnerSource];