@useorgx/openclaw-plugin 0.4.5 → 0.4.8

package/dist/index.js

@@ -12,20 +12,25 @@
  */
 import { OrgXClient } from "./api.js";
 import { createHttpHandler } from "./http-handler.js";
-import { readFileSync } from "node:fs";
+import { applyOrgxAgentSuitePlan, computeOrgxAgentSuitePlan } from "./agent-suite.js";
+import { registerArtifact } from "./artifacts/register-artifact.js";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { clearPersistedApiKey, loadAuthStore, resolveInstallationId, saveAuthStore, } from "./auth-store.js";
 import { clearPersistedSnapshot, readPersistedSnapshot, writePersistedSnapshot, } from "./snapshot-store.js";
 import { appendToOutbox, readOutbox, readOutboxSummary, replaceOutbox, } from "./outbox.js";
+import { getAgentContext, readAgentContexts } from "./agent-context-store.js";
+import { readAgentRuns, markAgentRunStopped } from "./agent-run-store.js";
 import { extractProgressOutboxMessage } from "./reporting/outbox-replay.js";
 import { ensureGatewayWatchdog } from "./gateway-watchdog.js";
-import { createMcpHttpHandler } from "./mcp-http-handler.js";
+import { createMcpHttpHandler, } from "./mcp-http-handler.js";
 import { autoConfigureDetectedMcpClients } from "./mcp-client-setup.js";
 import { readOpenClawGatewayPort, readOpenClawSettingsSnapshot } from "./openclaw-settings.js";
 import { posthogCapture } from "./telemetry/posthog.js";
+import { readSkillPackState, refreshSkillPackState } from "./skill-pack-state.js";
 export { OrgXClient } from "./api.js";
 const DEFAULT_BASE_URL = "https://www.useorgx.com";
 const DEFAULT_DOCS_URL = "https://orgx.mintlify.site/guides/openclaw-plugin-setup";
@@ -34,6 +39,16 @@ function isUserScopedApiKey(apiKey) {
 }
 function resolveRuntimeUserId(apiKey, candidates) {
     if (isUserScopedApiKey(apiKey)) {
+        // For oxk_ keys, the OrgX API ignores X-Orgx-User-Id, but we still keep a UUID
+        // around for created_by_id on certain entity writes (e.g., work_artifacts).
+        for (const candidate of candidates) {
+            if (typeof candidate !== "string")
+                continue;
+            const trimmed = candidate.trim();
+            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)) {
+                return trimmed;
+            }
+        }
         return "";
     }
     for (const candidate of candidates) {
@@ -186,6 +201,7 @@ function resolveConfig(api, input) {
         baseUrl,
         syncIntervalMs: pluginConf.syncIntervalMs ?? 300_000,
         enabled: pluginConf.enabled ?? true,
+        autoInstallAgentSuiteOnConnect: pluginConf.autoInstallAgentSuiteOnConnect ?? true,
         dashboardEnabled: pluginConf.dashboardEnabled ?? true,
         installationId: input.installationId,
         pluginVersion: resolvePluginVersion(),
@@ -268,6 +284,29 @@ function isUuid(value) {
         return false;
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
+function inferReportingInitiativeId(input) {
+    const env = pickNonEmptyString(process.env.ORGX_INITIATIVE_ID);
+    if (isUuid(env))
+        return env;
+    const agentId = pickNonEmptyString(input.agent_id, input.agentId);
+    if (agentId) {
+        const ctx = getAgentContext(agentId);
+        const ctxInit = ctx?.initiativeId ?? undefined;
+        if (isUuid(ctxInit ?? undefined))
+            return ctxInit ?? undefined;
+    }
+    // Fall back to the most recently updated agent context with a UUID initiative id.
+    try {
+        const store = readAgentContexts();
+        const candidates = Object.values(store.agents ?? {}).filter((ctx) => isUuid(ctx?.initiativeId ?? undefined));
+        candidates.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+        const picked = candidates[0]?.initiativeId ?? undefined;
+        return isUuid(picked) ? picked : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function toReportingPhase(phase, progressPct) {
     if (progressPct === 100)
         return "completed";
@@ -363,11 +402,66 @@ export default function register(api) {
         pollIntervalMs: null,
     };
     let activePairing = null;
-    const baseApiUrl = config.baseUrl.replace(/\/+$/, "");
+    // NOTE: base URL can be updated at runtime (e.g. user edits OpenClaw config). Keep it mutable.
+    let baseApiUrl = config.baseUrl.replace(/\/+$/, "");
     const defaultReportingCorrelationId = pickNonEmptyString(process.env.ORGX_CORRELATION_ID) ??
         `openclaw-${config.installationId}`;
+    function refreshConfigFromSources(input) {
+        const allowApiKeyChanges = input?.allowApiKeyChanges !== false;
+        const previousApiKey = config.apiKey;
+        const previousBaseUrl = config.baseUrl;
+        const previousUserId = config.userId;
+        const previousDocsUrl = config.docsUrl;
+        const previousKeySource = config.apiKeySource;
+        const latestPersisted = loadAuthStore();
+        const next = resolveConfig(api, {
+            installationId: config.installationId,
+            persistedApiKey: latestPersisted?.apiKey ?? null,
+            persistedUserId: latestPersisted?.userId ?? null,
+        });
+        const nextApiKey = allowApiKeyChanges ? next.apiKey : previousApiKey;
+        const nextUserId = allowApiKeyChanges ? next.userId : previousUserId;
+        const changed = nextApiKey !== previousApiKey ||
+            next.baseUrl !== previousBaseUrl ||
+            nextUserId !== previousUserId ||
+            next.docsUrl !== previousDocsUrl ||
+            next.apiKeySource !== previousKeySource;
+        if (!changed) {
+            return false;
+        }
+        if (allowApiKeyChanges) {
+            config.apiKey = nextApiKey;
+            config.userId = nextUserId;
+            config.apiKeySource = next.apiKeySource;
+        }
+        config.baseUrl = next.baseUrl;
+        config.docsUrl = next.docsUrl;
+        baseApiUrl = config.baseUrl.replace(/\/+$/, "");
+        client.setCredentials({
+            apiKey: config.apiKey,
+            userId: config.userId,
+            baseUrl: config.baseUrl,
+        });
+        // Keep onboarding state aligned with what's actually configured (without forcing a status transition).
+        updateOnboardingState({
+            hasApiKey: Boolean(config.apiKey),
+            keySource: config.apiKeySource,
+            docsUrl: config.docsUrl,
+            installationId: config.installationId,
+        });
+        api.log?.info?.("[orgx] Config refreshed", {
+            reason: input?.reason ?? "runtime_refresh",
+            baseUrl: config.baseUrl,
+            hasApiKey: Boolean(config.apiKey),
+            apiKeySource: config.apiKeySource,
+        });
+        return true;
+    }
     function resolveReportingContext(input) {
-        const initiativeId = pickNonEmptyString(input.initiative_id, input.initiativeId, process.env.ORGX_INITIATIVE_ID);
+        let initiativeId = pickNonEmptyString(input.initiative_id, input.initiativeId, process.env.ORGX_INITIATIVE_ID);
+        if (!isUuid(initiativeId)) {
+            initiativeId = inferReportingInitiativeId(input);
+        }
         if (!initiativeId || !isUuid(initiativeId)) {
             return {
                 ok: false,
@@ -411,6 +505,16 @@ export default function register(api) {
             return err.message;
         return typeof err === "string" ? err : "Unexpected error";
     }
+    function stableHash(value) {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    function isAuthFailure(err) {
+        const message = toErrorMessage(err).toLowerCase();
+        return (message.includes("401") ||
+            message.includes("unauthorized") ||
+            message.includes("invalid_token") ||
+            message.includes("invalid api key"));
+    }
     const registerTool = api.registerTool.bind(api);
     api.registerTool = (tool, options) => {
         const toolName = tool.name;
@@ -562,22 +666,47 @@ export default function register(api) {
     }
     function buildManualKeyConnectUrl() {
         try {
-            return new URL("/settings", baseApiUrl).toString();
+            // Deep-link into the Security section where API keys live.
+            return new URL("/settings#security", baseApiUrl).toString();
         }
         catch {
-            return "https://www.useorgx.com/settings";
+            return "https://www.useorgx.com/settings#security";
         }
     }
-    async function fetchOrgxJson(method, path, body) {
+    async function fetchOrgxJson(method, path, body, options) {
         try {
-            const response = await fetch(`${baseApiUrl}${path}`, {
-                method,
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                body: body ? JSON.stringify(body) : undefined,
-            });
-            const payload = (await response.json().catch(() => null));
+            const controller = new AbortController();
+            const timeoutMs = typeof options?.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
+                ? Math.max(1_000, Math.floor(options.timeoutMs))
+                : 12_000;
+            const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            let rawText = "";
+            try {
+                response = await fetch(`${baseApiUrl}${path}`, {
+                    method,
+                    signal: controller.signal,
+                    headers: {
+                        Accept: "application/json",
+                        "Content-Type": "application/json",
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                });
+                rawText = await response.text().catch(() => "");
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            const payload = (() => {
+                if (!rawText)
+                    return null;
+                try {
+                    return JSON.parse(rawText);
+                }
+                catch {
+                    return null;
+                }
+            })();
             if (!response.ok) {
                 const rawError = payload?.error ?? payload?.message;
                 let errorMessage;
@@ -590,18 +719,62 @@ export default function register(api) {
                     typeof rawError.message === "string") {
                     errorMessage = rawError.message;
                 }
+                else if (rawText && rawText.trim().length > 0) {
+                    // Avoid dumping HTML (Cloudflare / Next.js error pages) into UI; keep it short.
+                    const sanitized = rawText
+                        .replace(/\s+/g, " ")
+                        .replace(/<[^>]+>/g, "")
+                        .trim();
+                    errorMessage = sanitized.length > 0 ? sanitized.slice(0, 180) : `OrgX request failed (${response.status})`;
+                }
                 else {
                     errorMessage = `OrgX request failed (${response.status})`;
                 }
-                return { ok: false, status: response.status, error: errorMessage };
+                const statusToken = `HTTP ${response.status}`;
+                if (response.status &&
+                    !errorMessage.toLowerCase().includes(statusToken.toLowerCase()) &&
+                    !errorMessage.includes(`(${response.status})`)) {
+                    errorMessage = `${errorMessage} (HTTP ${response.status})`;
+                }
+                const debugParts = [];
+                const requestId = response.headers.get("x-request-id");
+                const vercelId = response.headers.get("x-vercel-id");
+                const cfRay = response.headers.get("cf-ray");
+                const clerkStatus = response.headers.get("x-clerk-auth-status");
+                const clerkReason = response.headers.get("x-clerk-auth-reason");
+                if (requestId)
+                    debugParts.push(`req=${requestId}`);
+                if (vercelId && vercelId !== requestId)
+                    debugParts.push(`vercel=${vercelId}`);
+                if (cfRay)
+                    debugParts.push(`cf-ray=${cfRay}`);
+                if (clerkStatus)
+                    debugParts.push(`clerk=${clerkStatus}`);
+                if (clerkReason)
+                    debugParts.push(`clerk_reason=${clerkReason}`);
+                const debugSuffix = debugParts.length > 0 ? ` (${debugParts.join(", ")})` : "";
+                return {
+                    ok: false,
+                    status: response.status,
+                    error: `${errorMessage}${debugSuffix}`,
+                };
             }
             if (payload?.data !== undefined) {
                 return { ok: true, data: payload.data };
             }
-            return { ok: true, data: payload };
+            if (payload !== null) {
+                return { ok: true, data: payload };
+            }
+            return { ok: true, data: rawText };
         }
         catch (err) {
-            return { ok: false, status: 0, error: toErrorMessage(err) };
+            const message = err &&
+                typeof err === "object" &&
+                "name" in err &&
+                err.name === "AbortError"
+                ? `OrgX request timed out (method=${method}, path=${path})`
+                : toErrorMessage(err);
+            return { ok: false, status: 0, error: message };
         }
     }
     function setRuntimeApiKey(input) {
@@ -664,6 +837,7 @@ export default function register(api) {
         const probeRemote = input.probeRemote === true;
         const outbox = await readOutboxSummary();
         const checks = [];
+        refreshConfigFromSources({ reason: "health_check" });
         const hasApiKey = Boolean(config.apiKey);
         if (hasApiKey) {
             checks.push({
@@ -721,7 +895,9 @@ export default function register(api) {
             else {
                 const startedAt = Date.now();
                 try {
-                    await client.getOrgSnapshot();
+                    // Avoid probing with /api/client/sync: it's heavier than necessary and can
+                    // create false negatives during transient server slowness.
+                    await client.getBillingStatus();
                     remoteReachable = true;
                     remoteLatencyMs = Date.now() - startedAt;
                     checks.push({
@@ -816,8 +992,313 @@ export default function register(api) {
             .filter(Boolean);
         return strings.length > 0 ? strings : undefined;
     }
+    function isPidAlive(pid) {
+        if (!Number.isFinite(pid) || !pid || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    function toFiniteNumber(value) {
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+        if (typeof value === "string" && value.trim().length > 0) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        return null;
+    }
+    function isSafePathSegment(value) {
+        const normalized = value.trim();
+        if (!normalized || normalized === "." || normalized === "..")
+            return false;
+        if (normalized.includes("/") || normalized.includes("\\") || normalized.includes("\0")) {
+            return false;
+        }
+        if (normalized.includes(".."))
+            return false;
+        return true;
+    }
+    function parseRetroEntityType(value) {
+        if (!value)
+            return undefined;
+        switch (value) {
+            case "initiative":
+            case "workstream":
+            case "milestone":
+            case "task":
+                return value;
+            default:
+                return undefined;
+        }
+    }
+    function readOpenClawSessionSummary(input) {
+        const agentId = input.agentId.trim();
+        const sessionId = input.sessionId.trim();
+        if (!agentId || !sessionId) {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+        if (!isSafePathSegment(agentId) || !isSafePathSegment(sessionId)) {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+        const jsonlPath = join(homedir(), ".openclaw", "agents", agentId, "sessions", `${sessionId}.jsonl`);
+        try {
+            if (!existsSync(jsonlPath)) {
+                return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+            }
+            const raw = readFileSync(jsonlPath, "utf8");
+            const lines = raw.split("\n");
+            let tokens = 0;
+            let costUsd = 0;
+            let hadError = false;
+            let errorMessage = null;
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const evt = JSON.parse(trimmed);
+                    if (evt.type !== "message")
+                        continue;
+                    const msg = evt.message;
+                    if (!msg || typeof msg !== "object")
+                        continue;
+                    const usage = msg.usage;
+                    if (usage && typeof usage === "object") {
+                        const totalTokens = toFiniteNumber(usage.totalTokens) ??
+                            toFiniteNumber(usage.total_tokens) ??
+                            null;
+                        const inputTokens = toFiniteNumber(usage.input) ?? 0;
+                        const outputTokens = toFiniteNumber(usage.output) ?? 0;
+                        const cacheReadTokens = toFiniteNumber(usage.cacheRead) ?? 0;
+                        const cacheWriteTokens = toFiniteNumber(usage.cacheWrite) ?? 0;
+                        tokens += Math.max(0, Math.round(totalTokens ??
+                            inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens));
+                        const cost = usage.cost;
+                        const costTotal = cost ? toFiniteNumber(cost.total) : null;
+                        if (costTotal !== null) {
+                            costUsd += Math.max(0, costTotal);
+                        }
+                    }
+                    const stopReason = typeof msg.stopReason === "string" ? msg.stopReason : "";
+                    const msgError = typeof msg.errorMessage === "string" && msg.errorMessage.trim().length > 0
+                        ? msg.errorMessage.trim()
+                        : null;
+                    if (stopReason === "error" || msgError) {
+                        hadError = true;
+                        errorMessage = msgError ?? errorMessage;
+                    }
+                }
+                catch {
+                    // Ignore malformed lines.
+                }
+            }
+            return {
+                tokens,
+                costUsd: Math.round(costUsd * 10_000) / 10_000,
+                hadError,
+                errorMessage,
+            };
+        }
+        catch {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+    }
+    async function reconcileStoppedAgentRuns() {
+        try {
+            const store = readAgentRuns();
+            const runs = Object.values(store.runs ?? {});
+            for (const run of runs) {
+                if (!run || typeof run !== "object")
+                    continue;
+                if (run.status !== "running")
+                    continue;
+                if (!run.pid || isPidAlive(run.pid))
+                    continue;
+                const stopped = markAgentRunStopped(run.runId);
+                if (!stopped)
+                    continue;
+                const initiativeId = stopped.initiativeId?.trim() ?? "";
+                if (!initiativeId)
+                    continue;
+                const summary = readOpenClawSessionSummary({
+                    agentId: stopped.agentId,
+                    sessionId: stopped.runId,
+                });
+                const completedAt = stopped.stoppedAt ?? new Date().toISOString();
+                const success = !summary.hadError;
+                const correlationId = stopped.runId;
+                const outcomePayload = {
+                    initiative_id: initiativeId,
+                    correlation_id: correlationId,
+                    source_client: "openclaw",
+                    execution_id: `openclaw:${stopped.runId}`,
+                    execution_type: "openclaw.session",
+                    agent_id: stopped.agentId,
+                    task_type: stopped.taskId ?? undefined,
+                    started_at: stopped.startedAt,
+                    completed_at: completedAt,
+                    inputs: {
+                        message: stopped.message,
+                        workstream_id: stopped.workstreamId,
+                        task_id: stopped.taskId,
+                    },
+                    outputs: {
+                        had_error: summary.hadError,
+                        error_message: summary.errorMessage,
+                    },
+                    steps: [],
+                    success,
+                    human_interventions: 0,
+                    errors: summary.errorMessage ? [summary.errorMessage] : [],
+                    metadata: {
+                        provider: stopped.provider,
+                        model: stopped.model,
+                        tokens: summary.tokens,
+                        cost_usd: summary.costUsd,
+                        source: "openclaw_agent_run_reconcile",
+                    },
+                };
+                const retroEntityType = stopped.taskId
+                    ? "task"
+                    : "initiative";
+                const retroEntityId = stopped.taskId ?? initiativeId;
+                const retroSummary = stopped.taskId
+                    ? `OpenClaw ${success ? "completed" : "blocked"} task ${stopped.taskId}.`
+                    : `OpenClaw run ${success ? "completed" : "blocked"} (session ${stopped.runId}).`;
+                const retroPayload = {
+                    initiative_id: initiativeId,
+                    correlation_id: correlationId,
+                    source_client: "openclaw",
+                    entity_type: retroEntityType,
+                    entity_id: retroEntityId,
+                    title: stopped.taskId ?? stopped.runId,
+                    idempotency_key: `retro:${stopped.runId}`,
+                    retro: {
+                        summary: retroSummary,
+                        what_went_well: success ? ["Completed without runtime error."] : [],
+                        what_went_wrong: success
+                            ? []
+                            : [summary.errorMessage ?? "Session ended with error."],
+                        decisions: [],
+                        follow_ups: success
+                            ? []
+                            : [
+                                {
+                                    title: "Investigate OpenClaw session failure and unblock task",
+                                    priority: "p0",
+                                    reason: summary.errorMessage ?? "Session ended with error.",
+                                },
+                            ],
+                        signals: {
+                            tokens: summary.tokens,
+                            cost_usd: summary.costUsd,
+                            had_error: summary.hadError,
+                            error_message: summary.errorMessage,
+                            session_id: stopped.runId,
+                            task_id: stopped.taskId,
+                            workstream_id: stopped.workstreamId,
+                            provider: stopped.provider,
+                            model: stopped.model,
+                            source: "openclaw_agent_run_reconcile",
+                        },
+                    },
+                };
+                try {
+                    await client.recordRunOutcome(outcomePayload);
+                }
+                catch (err) {
+                    const timestamp = new Date().toISOString();
+                    const activityItem = {
+                        id: randomUUID(),
+                        type: "run_completed",
+                        title: `Buffered outcome for session ${stopped.runId}`,
+                        description: null,
+                        agentId: stopped.agentId,
+                        agentName: null,
+                        requesterAgentId: stopped.agentId ?? null,
+                        requesterAgentName: null,
+                        executorAgentId: stopped.agentId ?? null,
+                        executorAgentName: null,
+                        runId: stopped.runId,
+                        initiativeId,
+                        timestamp,
+                        phase: success ? "completed" : "blocked",
+                        summary: retroSummary,
+                        metadata: {
+                            source: "openclaw_local_fallback",
+                            error: toErrorMessage(err),
+                        },
+                    };
+                    await appendToOutbox(initiativeId, {
+                        id: randomUUID(),
+                        type: "outcome",
+                        timestamp,
+                        payload: outcomePayload,
+                        activityItem,
+                    });
+                }
+                try {
+                    await client.recordRunRetro(retroPayload);
+                }
+                catch (err) {
+                    const timestamp = new Date().toISOString();
+                    const activityItem = {
+                        id: randomUUID(),
+                        type: "artifact_created",
+                        title: `Buffered retro for session ${stopped.runId}`,
+                        description: null,
+                        agentId: stopped.agentId,
+                        agentName: null,
+                        requesterAgentId: stopped.agentId ?? null,
+                        requesterAgentName: null,
+                        executorAgentId: stopped.agentId ?? null,
+                        executorAgentName: null,
+                        runId: stopped.runId,
+                        initiativeId,
+                        timestamp,
+                        phase: success ? "completed" : "blocked",
+                        summary: retroSummary,
+                        metadata: {
+                            source: "openclaw_local_fallback",
+                            error: toErrorMessage(err),
+                        },
+                    };
+                    await appendToOutbox(initiativeId, {
+                        id: randomUUID(),
+                        type: "retro",
+                        timestamp,
+                        payload: retroPayload,
+                        activityItem,
+                    });
+                }
+            }
+        }
+        catch {
+            // best effort
+        }
+    }
     async function replayOutboxEvent(event) {
         const payload = event.payload ?? {};
+        function normalizeRunFields(context) {
+            // We prefer correlation IDs for replay because many local adapters use UUID-like
+            // session IDs that do *not* exist as server-side run IDs.
+            if (context.correlationId) {
+                return { run_id: undefined, correlation_id: context.correlationId };
+            }
+            if (context.runId) {
+                return {
+                    run_id: undefined,
+                    correlation_id: `openclaw_run_${stableHash(context.runId).slice(0, 24)}`,
+                };
+            }
+            return { run_id: undefined, correlation_id: undefined };
+        }
         if (event.type === "progress") {
             const message = extractProgressOutboxMessage(payload);
             if (!message) {
@@ -848,7 +1329,12 @@ export default function register(api) {
             const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
                 ? metaRaw
                 : {};
-            const emitPayload = {
+            const baseMetadata = {
+                ...meta,
+                source: "orgx_openclaw_outbox_replay",
+                outbox_event_id: event.id,
+            };
+            let emitPayload = {
                 initiative_id: context.value.initiativeId,
                 run_id: context.value.runId,
                 correlation_id: context.value.correlationId,
@@ -860,12 +1346,22 @@ export default function register(api) {
                 next_step: pickStringField(payload, "next_step") ??
                     pickStringField(payload, "nextStep") ??
                     undefined,
-                metadata: {
-                    ...meta,
-                    source: "orgx_openclaw_outbox_replay",
-                    outbox_event_id: event.id,
-                },
+                metadata: baseMetadata,
             };
+            // Locally-buffered progress events often store a local UUID in run_id. OrgX may reject
+            // unknown run IDs on replay; prefer a deterministic non-UUID correlation key instead.
+            if (emitPayload.run_id && !emitPayload.correlation_id) {
+                const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
+                emitPayload = {
+                    ...emitPayload,
+                    run_id: undefined,
+                    correlation_id: replayCorrelationId,
+                    metadata: {
+                        ...(emitPayload.metadata ?? {}),
+                        replay_run_id_as_correlation: true,
+                    },
+                };
+            }
             try {
                 await client.emitActivity(emitPayload);
             }
@@ -879,14 +1375,13 @@ export default function register(api) {
                     /^404\\b/.test(msg) &&
                     /\\brun\\b/i.test(msg) &&
                     /not found/i.test(msg)) {
+                    const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
                     await client.emitActivity({
                         ...emitPayload,
                         run_id: undefined,
-                        // Avoid passing a bare UUID as correlation_id since some server
-                        // paths may interpret UUIDs as run_id lookups.
-                        correlation_id: `openclaw:${emitPayload.run_id}`,
+                        correlation_id: replayCorrelationId,
                         metadata: {
-                            ...emitPayload.metadata,
+                            ...(emitPayload.metadata ?? {}),
                             replay_run_id_as_correlation: true,
                         },
                     });
@@ -909,12 +1404,29 @@ export default function register(api) {
             if (!context.ok) {
                 throw new Error(context.error);
             }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote decision.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "decision",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                question,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:decision:${fallbackKey}`;
             await client.applyChangeset({
                 initiative_id: context.value.initiativeId,
-                run_id: context.value.runId,
-                correlation_id: context.value.correlationId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
                 source_client: context.value.sourceClient,
-                idempotency_key: pickStringField(payload, "idempotency_key") ?? `decision:${event.id}`,
+                idempotency_key: resolvedIdempotencyKey,
                 operations: [
                     {
                         op: "decision.create",
@@ -933,6 +1445,10 @@ export default function register(api) {
             if (!context.ok) {
                 throw new Error(context.error);
             }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
             const operations = Array.isArray(payload.operations)
                 ? payload.operations
                 : [];
@@ -942,31 +1458,267 @@ export default function register(api) {
                 });
                 return;
             }
+            // Status updates are the most common offline replay payload, and `updateEntity`
+            // is the most widely supported primitive across OrgX deployments. Prefer it
+            // when the changeset contains only simple status mutations.
+            const statusOps = operations
+                .map((op) => {
+                if (!op || typeof op !== "object")
+                    return null;
+                const record = op;
+                const kind = typeof record.op === "string" ? record.op.trim() : "";
+                if (kind === "task.update") {
+                    const taskId = typeof record.task_id === "string" ? record.task_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "completed" || normalized === "complete" || normalized === "finished"
+                        ? "done"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized;
+                    if (!taskId || !status)
+                        return null;
+                    return { type: "task", id: taskId, status };
+                }
+                if (kind === "milestone.update") {
+                    const milestoneId = typeof record.milestone_id === "string" ? record.milestone_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "done" || normalized === "complete" || normalized === "finished"
+                        ? "completed"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized === "todo" || normalized === "not_started" || normalized === "pending"
+                                ? "planned"
+                                : normalized === "blocked" || normalized === "stuck"
+                                    ? "at_risk"
+                                    : normalized;
+                    if (!milestoneId || !status)
+                        return null;
+                    return { type: "milestone", id: milestoneId, status };
+                }
+                return null;
+            })
+                .filter((item) => Boolean(item));
+            if (statusOps.length === operations.length) {
+                for (const op of statusOps) {
+                    await client.updateEntity(op.type, op.id, { status: op.status });
+                }
+                return;
+            }
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote change.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "changeset",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                operations,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:changeset:${fallbackKey}`;
             await client.applyChangeset({
                 initiative_id: context.value.initiativeId,
-                run_id: context.value.runId,
-                correlation_id: context.value.correlationId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
                 source_client: context.value.sourceClient,
-                idempotency_key: pickStringField(payload, "idempotency_key") ?? `changeset:${event.id}`,
+                idempotency_key: resolvedIdempotencyKey,
                 operations,
             });
             return;
         }
+        if (event.type === "outcome") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const executionId = pickStringField(payload, "execution_id") ??
+                pickStringField(payload, "executionId");
+            const executionType = pickStringField(payload, "execution_type") ??
+                pickStringField(payload, "executionType");
+            const agentId = pickStringField(payload, "agent_id") ??
+                pickStringField(payload, "agentId");
+            const success = typeof payload.success === "boolean"
+                ? payload.success
+                : null;
+            if (!executionId || !executionType || !agentId || success === null) {
+                api.log?.warn?.("[orgx] Dropping invalid outcome outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const metaRaw = payload.metadata;
+            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
+                ? metaRaw
+                : {};
+            await client.recordRunOutcome({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                execution_id: executionId,
+                execution_type: executionType,
+                agent_id: agentId,
+                task_type: pickStringField(payload, "task_type") ??
+                    pickStringField(payload, "taskType") ??
+                    undefined,
+                domain: pickStringField(payload, "domain") ?? undefined,
+                started_at: pickStringField(payload, "started_at") ??
+                    pickStringField(payload, "startedAt") ??
+                    undefined,
+                completed_at: pickStringField(payload, "completed_at") ??
+                    pickStringField(payload, "completedAt") ??
+                    undefined,
+                inputs: payload.inputs && typeof payload.inputs === "object"
+                    ? payload.inputs
+                    : undefined,
+                outputs: payload.outputs && typeof payload.outputs === "object"
+                    ? payload.outputs
+                    : undefined,
+                steps: Array.isArray(payload.steps)
+                    ? payload.steps
+                    : undefined,
+                success,
+                quality_score: typeof payload.quality_score === "number"
+                    ? payload.quality_score
+                    : typeof payload.qualityScore === "number"
+                        ? payload.qualityScore
+                        : undefined,
+                duration_vs_estimate: typeof payload.duration_vs_estimate === "number"
+                    ? payload.duration_vs_estimate
+                    : typeof payload.durationVsEstimate === "number"
+                        ? payload.durationVsEstimate
+                        : undefined,
+                cost_vs_budget: typeof payload.cost_vs_budget === "number"
+                    ? payload.cost_vs_budget
+                    : typeof payload.costVsBudget === "number"
+                        ? payload.costVsBudget
+                        : undefined,
+                human_interventions: typeof payload.human_interventions === "number"
+                    ? payload.human_interventions
+                    : typeof payload.humanInterventions === "number"
+                        ? payload.humanInterventions
+                        : undefined,
+                user_satisfaction: typeof payload.user_satisfaction === "number"
+                    ? payload.user_satisfaction
+                    : typeof payload.userSatisfaction === "number"
+                        ? payload.userSatisfaction
+                        : undefined,
+                errors: Array.isArray(payload.errors)
+                    ? payload.errors.filter((e) => typeof e === "string")
+                    : undefined,
+                metadata: {
+                    ...meta,
+                    source: "orgx_openclaw_outbox_replay",
+                    outbox_event_id: event.id,
+                },
+            });
+            return;
+        }
+        if (event.type === "retro") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const retro = payload.retro && typeof payload.retro === "object" && !Array.isArray(payload.retro)
+                ? payload.retro
+                : null;
+            const summary = retro && typeof retro.summary === "string" ? retro.summary.trim() : "";
+            if (!retro || !summary) {
+                api.log?.warn?.("[orgx] Dropping invalid retro outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const entityTypeRaw = pickStringField(payload, "entity_type") ??
+                pickStringField(payload, "entityType");
+            const parsedEntityType = parseRetroEntityType(entityTypeRaw) ?? null;
+            // Server-side enum parity can lag behind local clients. Only attach to the
+            // entity types that are guaranteed to exist today.
+            const entityType = parsedEntityType === "initiative" || parsedEntityType === "task"
+                ? parsedEntityType
+                : null;
+            const entityIdRaw = pickStringField(payload, "entity_id") ??
+                pickStringField(payload, "entityId") ??
+                null;
+            const entityId = isUuid(entityIdRaw ?? undefined) ? entityIdRaw : null;
+            await client.recordRunRetro({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                entity_type: entityType && entityId ? entityType : undefined,
+                entity_id: entityType && entityId ? entityId : undefined,
+                title: pickStringField(payload, "title") ?? undefined,
+                idempotency_key: pickStringField(payload, "idempotency_key") ??
+                    pickStringField(payload, "idempotencyKey") ??
+                    undefined,
+                retro: retro,
+                markdown: pickStringField(payload, "markdown") ?? undefined,
+            });
+            return;
+        }
         if (event.type === "artifact") {
-            const name = pickStringField(payload, "name");
-            if (!name) {
+            // Artifacts are first-class UX loop closure (activity stream + entity modals).
+            // Try to persist upstream; if this fails, keep the event queued for retry.
+            const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+                ? event.payload
+                : {};
+            const name = pickStringField(payload, "name") ?? pickStringField(payload, "title") ?? "";
+            const artifactType = pickStringField(payload, "artifact_type") ?? "other";
+            const entityType = pickStringField(payload, "entity_type") ?? "";
+            const entityId = pickStringField(payload, "entity_id") ?? "";
+            const artifactId = pickStringField(payload, "artifact_id") ?? null;
+            const description = pickStringField(payload, "description") ?? undefined;
+            const externalUrl = pickStringField(payload, "url") ?? pickStringField(payload, "artifact_url") ?? null;
+            const content = pickStringField(payload, "content") ?? pickStringField(payload, "preview_markdown") ?? null;
+            const allowedEntityType = entityType === "initiative" ||
+                entityType === "milestone" ||
+                entityType === "task" ||
+                entityType === "decision" ||
+                entityType === "project"
+                ? entityType
+                : null;
+            if (!allowedEntityType || !entityId.trim() || !name.trim()) {
                 api.log?.warn?.("[orgx] Dropping invalid artifact outbox event", {
                     eventId: event.id,
+                    entityType,
+                    entityId,
                 });
                 return;
             }
-            await client.createEntity("artifact", {
-                name,
-                artifact_type: pickStringField(payload, "artifact_type") ?? "other",
-                description: pickStringField(payload, "description"),
-                artifact_url: pickStringField(payload, "url"),
-                status: "active",
+            const result = await registerArtifact(client, client.getBaseUrl(), {
+                artifact_id: artifactId,
+                entity_type: allowedEntityType,
+                entity_id: entityId,
+                name: name.trim(),
+                artifact_type: artifactType.trim() || "other",
+                description,
+                external_url: externalUrl,
+                preview_markdown: content,
+                status: "draft",
+                metadata: {
+                    source: "outbox_replay",
+                    outbox_event_id: event.id,
+                    ...(payload.metadata && typeof payload.metadata === "object" && !Array.isArray(payload.metadata)
+                        ? payload.metadata
+                        : {}),
+                },
+                validate_persistence: process.env.ORGX_VALIDATE_ARTIFACT_PERSISTENCE === "1",
             });
+            if (!result.ok) {
+                throw new Error(result.persistence.last_error ?? "artifact registration failed");
+            }
             return;
         }
     }
@@ -1040,6 +1792,9 @@ export default function register(api) {
             return syncInFlight;
         }
         syncInFlight = (async () => {
+            if (!config.apiKey) {
+                refreshConfigFromSources({ reason: "sync_no_api_key" });
+            }
             if (!config.apiKey) {
                 updateOnboardingState({
                     status: "idle",
@@ -1050,25 +1805,123 @@ export default function register(api) {
                 return;
             }
             try {
-                updateCachedSnapshot(await client.getOrgSnapshot());
+                await reconcileStoppedAgentRuns();
+                let snapshotError = null;
+                try {
+                    updateCachedSnapshot(await client.getOrgSnapshot());
+                }
+                catch (err) {
+                    if (isAuthFailure(err)) {
+                        throw err;
+                    }
+                    snapshotError = toErrorMessage(err);
+                    api.log?.warn?.("[orgx] Snapshot sync failed (continuing)", {
+                        error: snapshotError,
+                    });
+                }
+                // Best-effort: poll the canonical OrgX SkillPack so the dashboard/install path
+                // can apply it without blocking on an on-demand fetch.
+                try {
+                    const refreshed = await refreshSkillPackState({
+                        getSkillPack: (args) => client.getSkillPack(args),
+                    });
+                    if (refreshed.changed) {
+                        void posthogCapture({
+                            event: "openclaw_skill_pack_updated",
+                            distinctId: config.installationId,
+                            properties: {
+                                plugin_version: config.pluginVersion,
+                                skill_pack_name: refreshed.state.pack?.name ?? null,
+                                skill_pack_version: refreshed.state.pack?.version ?? null,
+                                skill_pack_checksum: refreshed.state.pack?.checksum ?? null,
+                            },
+                        }).catch(() => {
+                            // best effort
+                        });
+                    }
+                }
+                catch {
+                    // best effort
+                }
+                // Best-effort: provision/update the OrgX agent suite after we've verified a working connection.
+                // This makes domain agents available immediately for launches without requiring a manual install.
+                try {
+                    if (config.autoInstallAgentSuiteOnConnect !== false) {
+                        const state = readSkillPackState();
+                        const updateAvailable = Boolean(state.remote?.checksum &&
+                            state.pack?.checksum &&
+                            state.remote.checksum !== state.pack.checksum);
+                        const plan = computeOrgxAgentSuitePlan({
+                            packVersion: config.pluginVersion || "0.0.0",
+                            skillPack: state.overrides,
+                            skillPackRemote: state.remote,
+                            skillPackPolicy: state.policy,
+                            skillPackUpdateAvailable: updateAvailable,
+                        });
+                        const hasConflicts = (plan.workspaceFiles ?? []).some((f) => f.action === "conflict");
+                        const hasWork = Boolean(plan.openclawConfigWouldUpdate) ||
+                            (plan.workspaceFiles ?? []).some((f) => f.action !== "noop");
+                        if (hasWork && !hasConflicts) {
+                            const applied = applyOrgxAgentSuitePlan({
+                                plan,
+                                dryRun: false,
+                                skillPack: state.overrides,
+                            });
+                            void applied;
+                            void posthogCapture({
+                                event: "openclaw_agent_suite_auto_install",
+                                distinctId: config.installationId,
+                                properties: {
+                                    plugin_version: (config.pluginVersion ?? "").trim() || null,
+                                    skill_pack_source: plan.skillPack?.source ?? null,
+                                    skill_pack_checksum: plan.skillPack?.checksum ?? null,
+                                    skill_pack_version: plan.skillPack?.version ?? null,
+                                    openclaw_config_updated: Boolean(plan.openclawConfigWouldUpdate),
+                                },
+                            }).catch(() => {
+                                // best effort
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    api.log?.debug?.("[orgx] Agent suite auto-provision skipped/failed (best effort)", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
                 updateOnboardingState({
                     status: "connected",
                     hasApiKey: true,
-                    connectionVerified: true,
-                    lastError: null,
+                    connectionVerified: snapshotError === null,
+                    lastError: snapshotError,
                     nextAction: "open_dashboard",
                 });
                 await flushOutboxQueues();
                 api.log?.debug?.("[orgx] Sync OK");
             }
             catch (err) {
+                const authFailure = isAuthFailure(err);
+                const errorMessage = authFailure
+                    ? "Unauthorized. Your OrgX key may be revoked or expired. Reconnect in browser or use API key."
+                    : toErrorMessage(err);
                 updateOnboardingState({
                     status: "error",
                     hasApiKey: true,
                     connectionVerified: false,
-                    lastError: toErrorMessage(err),
+                    lastError: errorMessage,
                     nextAction: "reconnect",
                 });
+                if (authFailure) {
+                    void posthogCapture({
+                        event: "openclaw_sync_auth_failed",
+                        distinctId: config.installationId,
+                        properties: {
+                            plugin_version: config.pluginVersion,
+                        },
+                    }).catch(() => {
+                        // best effort
+                    });
+                }
                 api.log?.warn?.(`[orgx] Sync failed: ${err instanceof Error ? err.message : err}`);
             }
         })();
@@ -1100,7 +1953,10 @@ export default function register(api) {
             openclawVersion: input.openclawVersion,
             platform: input.platform || process.platform,
             deviceName: input.deviceName,
-        });
+        }, 
+        // Pairing can hit a cold serverless boot + supabase insert + rate-limit checks.
+        // Give it more headroom than typical lightweight API calls.
+        { timeoutMs: 30_000 });
         if (!started.ok) {
             if (isAuthRequiredError(started)) {
                 clearPairingState();
@@ -1124,7 +1980,8 @@ export default function register(api) {
                     state,
                 };
             }
-            const message = `Pairing start failed: ${started.error}`;
+            const statusLabel = started.status ? ` (HTTP ${started.status})` : "";
+            const message = `Pairing start failed${statusLabel}: ${started.error}`;
             updateOnboardingState({
                 status: "error",
                 hasApiKey: Boolean(config.apiKey),
@@ -1196,9 +2053,15 @@ export default function register(api) {
                     nextAction: "retry",
                 });
             }
+            const pairingUserIdRaw = typeof polled.data.supabaseUserId === "string"
+                ? polled.data.supabaseUserId
+                : typeof polled.data.userId === "string"
+                    ? polled.data.userId
+                    : null;
             setRuntimeApiKey({
                 apiKey: key,
                 source: "browser_pairing",
+                userId: resolveRuntimeUserId(key, [pairingUserIdRaw, config.userId]) || null,
                 workspaceName: polled.data.workspaceName ?? null,
                 keyPrefix: polled.data.keyPrefix ?? null,
             });
@@ -1875,6 +2738,48 @@ export default function register(api) {
             }
         },
     }, { optional: true });
+    function withProvenanceMetadata(metadata) {
+        const input = metadata ?? {};
+        const out = { ...input };
+        if (out.orgx_plugin_version === undefined) {
+            out.orgx_plugin_version = (config.pluginVersion ?? "").trim() || null;
+        }
+        try {
+            const state = readSkillPackState();
+            const overrides = state.overrides;
+            if (out.skill_pack_name === undefined) {
+                out.skill_pack_name = overrides?.name ?? state.pack?.name ?? null;
+            }
+            if (out.skill_pack_version === undefined) {
+                out.skill_pack_version = overrides?.version ?? state.pack?.version ?? null;
+            }
+            if (out.skill_pack_checksum === undefined) {
+                out.skill_pack_checksum = overrides?.checksum ?? state.pack?.checksum ?? null;
+            }
+            if (out.skill_pack_source === undefined) {
+                out.skill_pack_source = overrides?.source ?? null;
+            }
+            if (out.skill_pack_etag === undefined) {
+                out.skill_pack_etag = state.etag ?? null;
+            }
+        }
+        catch {
+            // best effort
+        }
+        if (out.orgx_provenance === undefined) {
+            out.orgx_provenance = {
+                plugin_version: out.orgx_plugin_version ?? null,
+                skill_pack: {
+                    name: out.skill_pack_name ?? null,
+                    version: out.skill_pack_version ?? null,
+                    checksum: out.skill_pack_checksum ?? null,
+                    source: out.skill_pack_source ?? null,
+                    etag: out.skill_pack_etag ?? null,
+                },
+            };
+        }
+        return out;
+    }
     async function emitActivityWithFallback(source, payload) {
         if (!payload.message || payload.message.trim().length === 0) {
             return text("❌ message is required");
@@ -1895,10 +2800,10 @@ export default function register(api) {
             progress_pct: payload.progress_pct,
             level: payload.level ?? "info",
             next_step: payload.next_step,
-            metadata: {
+            metadata: withProvenanceMetadata({
                 ...(payload.metadata ?? {}),
                 source,
-            },
+            }),
         };
         const activityItem = {
             id,
@@ -1907,6 +2812,10 @@ export default function register(api) {
             description: payload.next_step ?? null,
             agentId: null,
             agentName: null,
+            requesterAgentId: null,
+            requesterAgentName: null,
+            executorAgentId: null,
+            executorAgentName: null,
             runId: context.value.runId ?? null,
             initiativeId: context.value.initiativeId,
             timestamp: now,
@@ -1956,15 +2865,19 @@ export default function register(api) {
             description: `${payload.operations.length} operation${payload.operations.length === 1 ? "" : "s"}`,
             agentId: null,
             agentName: null,
+            requesterAgentId: null,
+            requesterAgentName: null,
+            executorAgentId: null,
+            executorAgentName: null,
             runId: context.value.runId ?? null,
             initiativeId: context.value.initiativeId,
             timestamp: now,
             phase: "review",
             summary: `${payload.operations.length} operation${payload.operations.length === 1 ? "" : "s"}`,
-            metadata: {
+            metadata: withProvenanceMetadata({
                 source,
                 idempotency_key: idempotencyKey,
-            },
+            }),
         };
         try {
             const result = await client.applyChangeset(requestPayload);
@@ -2235,18 +3148,30 @@ export default function register(api) {
     // --- orgx_register_artifact ---
     registerMcpTool({
         name: "orgx_register_artifact",
-        description: "Register a work output (PR, document, config change, report, etc.) with OrgX. Makes it visible in the dashboard.",
+        description: "Register a work output (PR, document, config change, report, etc.) as a work_artifact in OrgX. Makes it visible in the dashboard activity timeline and entity detail modals.",
         parameters: {
             type: "object",
             properties: {
+                initiative_id: {
+                    type: "string",
+                    description: "Convenience: initiative UUID. Used as entity_type='initiative', entity_id=<this> when entity_type/entity_id are not provided.",
+                },
+                entity_type: {
+                    type: "string",
+                    enum: ["initiative", "milestone", "task", "decision", "project"],
+                    description: "The type of entity this artifact is attached to",
+                },
+                entity_id: {
+                    type: "string",
+                    description: "UUID of the entity this artifact is attached to",
+                },
                 name: {
                     type: "string",
                     description: "Human-readable artifact name (e.g., 'PR #107: Fix build size')",
                 },
                 artifact_type: {
                     type: "string",
-                    enum: ["pr", "commit", "document", "config", "report", "design", "other"],
-                    description: "Type of artifact",
+                    description: "Artifact type code (e.g., 'eng.diff_pack', 'pr', 'document'). Falls back to 'shared.project_handbook' if the type is not recognized by OrgX.",
                 },
                 description: {
                     type: "string",
@@ -2254,7 +3179,11 @@ export default function register(api) {
                 },
                 url: {
                     type: "string",
-                    description: "Link to the artifact (PR URL, file path, etc.)",
+                    description: "External link to the artifact (PR URL, file path, etc.)",
+                },
+                content: {
+                    type: "string",
+                    description: "Inline preview content (markdown/text). At least one of url or content is required.",
                 },
             },
             required: ["name", "artifact_type"],
@@ -2263,6 +3192,32 @@ export default function register(api) {
         async execute(_callId, params = { name: "", artifact_type: "other" }) {
             const now = new Date().toISOString();
             const id = `artifact:${randomUUID().slice(0, 8)}`;
+            // Resolve entity association: explicit entity_type+entity_id > initiative_id > inferred
+            let resolvedEntityType = null;
+            let resolvedEntityId = null;
+            if (params.entity_type && isUuid(params.entity_id)) {
+                resolvedEntityType = params.entity_type;
+                resolvedEntityId = params.entity_id;
+            }
+            else if (isUuid(params.initiative_id)) {
+                resolvedEntityType = "initiative";
+                resolvedEntityId = params.initiative_id;
+            }
+            else {
+                const inferred = inferReportingInitiativeId(params);
+                if (inferred) {
+                    resolvedEntityType = "initiative";
+                    resolvedEntityId = inferred;
+                }
+            }
+            if (!resolvedEntityType || !resolvedEntityId) {
+                return text("❌ Cannot register artifact: provide entity_type + entity_id, or initiative_id, so the artifact can be attached to an entity.");
+            }
+            if (!params.url && !params.content) {
+                return text("❌ Cannot register artifact: provide at least one of url or content.");
+            }
+            const baseUrl = client.getBaseUrl();
+            const artifactId = randomUUID();
             const activityItem = {
                 id,
                 type: "artifact_created",
@@ -2270,32 +3225,66 @@ export default function register(api) {
                 description: params.description ?? null,
                 agentId: null,
                 agentName: null,
+                requesterAgentId: null,
+                requesterAgentName: null,
+                executorAgentId: null,
+                executorAgentName: null,
                 runId: null,
-                initiativeId: null,
+                initiativeId: resolvedEntityType === "initiative" ? resolvedEntityId : null,
                 timestamp: now,
                 summary: params.url ?? null,
-                metadata: {
+                metadata: withProvenanceMetadata({
                     source: "orgx_register_artifact",
                     artifact_type: params.artifact_type,
                     url: params.url,
-                },
+                    entity_type: resolvedEntityType,
+                    entity_id: resolvedEntityId,
+                }),
             };
             try {
-                const entity = await client.createEntity("artifact", {
+                const result = await registerArtifact(client, baseUrl, {
+                    artifact_id: artifactId,
+                    entity_type: resolvedEntityType,
+                    entity_id: resolvedEntityId,
                     name: params.name,
                     artifact_type: params.artifact_type,
-                    description: params.description,
-                    artifact_url: params.url,
-                    status: "active",
+                    description: params.description ?? null,
+                    external_url: params.url ?? null,
+                    preview_markdown: params.content ?? null,
+                    status: "draft",
+                    metadata: {
+                        source: "orgx_register_artifact",
+                        artifact_id: artifactId,
+                    },
+                    validate_persistence: true,
+                });
+                if (!result.ok) {
+                    throw new Error(result.persistence.last_error ?? "Artifact registration failed");
+                }
+                activityItem.metadata = withProvenanceMetadata({
+                    ...activityItem.metadata,
+                    artifact_id: result.artifact_id,
+                    entity_type: resolvedEntityType,
+                    entity_id: resolvedEntityId,
                 });
-                return json(`Artifact registered: ${params.name} [${params.artifact_type}]`, entity);
+                return json(`Artifact registered: ${params.name} [${params.artifact_type}] → ${resolvedEntityType}/${resolvedEntityId} (id: ${result.artifact_id})`, result);
             }
-            catch {
+            catch (firstError) {
+                // Outbox fallback for offline/error scenarios
                 await appendToOutbox("artifacts", {
                     id,
                     type: "artifact",
                     timestamp: now,
-                    payload: params,
+                    payload: {
+                        artifact_id: artifactId,
+                        name: params.name,
+                        artifact_type: params.artifact_type,
+                        description: params.description,
+                        url: params.url,
+                        content: params.content,
+                        entity_type: resolvedEntityType,
+                        entity_id: resolvedEntityId,
+                    },
                     activityItem,
                 });
                 return text(`Artifact saved locally: ${params.name} [${params.artifact_type}] (will sync when connected)`);
@@ -2406,8 +3395,29 @@ export default function register(api) {
     }, {
         getHealth: async (input = {}) => buildHealthReport({ probeRemote: input.probeRemote === true }),
     });
+    const mcpPromptRegistry = new Map();
+    mcpPromptRegistry.set("ship", {
+        name: "ship",
+        description: "Commit local changes, open a PR, and merge it (GitHub CLI required).",
+        arguments: [],
+        messages: [
+            {
+                role: "user",
+                content: [
+                    "Ship the current work:",
+                    "- Inspect `git status -sb` and `git diff --stat` and summarize what will be shipped.",
+                    "- Run `npm run typecheck`, `npm run test:hooks`, and `npm run build` (fix failures).",
+                    "- Create a feature branch if on `main`.",
+                    "- Commit with a clear message (do not include secrets).",
+                    "- Push branch, open a PR (use `gh pr create`), then merge it (use `gh pr merge --merge --auto`).",
+                    "- If `gh` is not authenticated, stop and tell me what to run.",
+                ].join("\n"),
+            },
+        ],
+    });
     const mcpHttpHandler = createMcpHttpHandler({
         tools: mcpToolRegistry,
+        prompts: mcpPromptRegistry,
         logger: api.log ?? {},
         serverName: "@useorgx/openclaw-plugin",
         serverVersion: config.pluginVersion,