carthagent 1.0.7 → 1.1.0-beta.1

package/plugins/carthagent/src/ui/workspace.tsx

@@ -0,0 +1,379 @@
+/** @jsxImportSource @opentui/solid */
+import { For, Show, createSignal, onCleanup, onMount } from "solid-js";
+import { usePlugin } from "@opencode/plugin/tui";
+import { pullRequestClient, rpcEventOptions, workspaceClient, type PullRequestRecord, type WorkspaceDelivery, type WorkspaceSnapshot } from "./client.js";
+import { createLatestRequestGate, onWorkspaceUpdated, renderDeliveryReadiness } from "./workspace-live.js";
+
+function sessionAttention(context: ReturnType<typeof usePlugin>, sessionID: string) {
+  return (context.data.session.permission.list(sessionID)?.length ?? 0) + (context.data.session.form.list(sessionID)?.length ?? 0);
+}
+
+export function WorkspacePage(props: { view: string; refreshKey?: string; sessionID?: string }) {
+  const context = usePlugin();
+  const [snapshot, setSnapshot] = createSignal<WorkspaceSnapshot>();
+  const [activeSessions, setActiveSessions] = createSignal<Record<string, { type: "running" }>>({});
+  const [deliveryEvidence, setDeliveryEvidence] = createSignal<WorkspaceDelivery>();
+  const [reviewEvidence, setReviewEvidence] = createSignal<unknown>();
+  const [inventorySessions, setInventorySessions] = createSignal<ReturnType<typeof context.data.session.list>>([]);
+  const [query, setQuery] = createSignal("");
+  const [error, setError] = createSignal("");
+  const [rpcConnected, setRpcConnected] = createSignal(true);
+  const [pullRequests, setPullRequests] = createSignal<Record<string, PullRequestRecord[]>>({});
+  const snapshotRequests = createLatestRequestGate();
+  const evidenceRequests = createLatestRequestGate();
+  const currentSessionID = () => {
+    const currentRoute = context.ui.router.current();
+    return props.sessionID ?? (currentRoute.type === "session" ? currentRoute.sessionID : currentRoute.type === "plugin" && currentRoute.name === "carthagent" && typeof currentRoute.data?.sessionID === "string" ? currentRoute.data.sessionID : undefined);
+  };
+  const sessionLocation = () => currentSessionID() ? context.data.session.get(currentSessionID()!)?.location : undefined;
+  const api = workspaceClient(context, sessionLocation);
+  const currentLocation = () => sessionLocation() ?? context.location ?? context.data.location.default();
+  const activeSession = () => {
+    const activeRoute = context.ui.router.current();
+    return activeRoute.type === "plugin" ? activeRoute.data?.sessionID ?? props.sessionID : activeRoute.type === "session" ? activeRoute.sessionID : props.sessionID;
+  };
+  const localSessions = () => inventorySessions().filter((session) => !session.parentID);
+  const syncNativeSessions = async (isCurrent: () => boolean, signal: AbortSignal) => {
+    const all = [] as ReturnType<typeof context.data.session.list>;
+    let cursor: string | undefined;
+    do {
+      const page = await context.client.session.list({ limit: 100, order: "desc", ...(cursor ? { cursor } : {}) }, { signal });
+      if (!isCurrent()) return;
+      all.push(...page.data);
+      cursor = page.cursor.next ?? undefined;
+    } while (cursor);
+    if (!isCurrent()) return;
+    const sessions = all.filter((session) => !session.parentID);
+    for (const session of sessions) {
+      if (!isCurrent()) return;
+      await Promise.allSettled([
+        context.data.session.sync(session.id),
+        context.data.session.permission.sync(session.id),
+        context.data.session.form.sync(session.id, session.location),
+      ]);
+    }
+    if (isCurrent()) setInventorySessions(all);
+  };
+  type WorkspaceSession = { id: string; title: string; directory: string; status: string; projectID?: string; attention?: number };
+  const workspaceSessions = (): WorkspaceSession[] => {
+    const snapshotSessions = snapshot()?.sessions ?? [];
+    const known = new Set(snapshotSessions.map((session) => session.id));
+    const projectIDs = new Set(snapshot()?.projects.map((project) => project.id) ?? []);
+    const projectDirectories = new Set(snapshot()?.projects.map((project) => project.directory) ?? []);
+    const nativeSessions = localSessions().filter((session) => !known.has(session.id) &&
+      (projectIDs.has(session.projectID) || projectDirectories.has(session.location.directory)));
+    return [
+      ...snapshotSessions.map((session): WorkspaceSession => ({ id: session.id, title: session.title, directory: session.directory, status: session.status, projectID: session.projectID, attention: sessionAttention(context, session.id) })),
+      ...nativeSessions.map((session) => ({ id: session.id, title: session.title ?? session.id, directory: session.location.directory, status: activeSessions()[session.id]?.type === "running" ? "running" : "idle", projectID: session.projectID, attention: sessionAttention(context, session.id) })),
+    ].filter((session) => !query() || `${session.title} ${session.id} ${session.directory}`.toLowerCase().includes(query().toLowerCase()));
+  };
+
+  const refresh = async (signal?: AbortSignal) => {
+    const request = snapshotRequests.begin();
+    if (!api) { if (request.isCurrent()) setError("Workspace service is not connected. Start the CTG-local workspace server to browse tasks and worktrees."); return; }
+    const requestSignal = signal ? AbortSignal.any([signal, request.signal]) : request.signal;
+    try {
+      const result = await api.snapshot(undefined, requestSignal);
+      if (!request.isCurrent()) return;
+      setSnapshot(result);
+      setRpcConnected(true);
+      setError("");
+    } catch (cause) {
+      if (request.isCurrent()) {
+        setRpcConnected(false);
+        setError(cause instanceof Error ? cause.message : String(cause));
+      }
+    }
+  };
+  onMount(() => {
+    let generation = 0;
+    let observedDirectory = currentLocation().directory;
+    let nativeAbort: AbortController | undefined;
+    let rehydrateAbort: AbortController | undefined;
+    let rpcAbort: AbortController | undefined;
+    let stopRpc: (() => void) | undefined;
+    const subscribeRpc = () => {
+      rpcAbort?.abort();
+      stopRpc?.();
+      if (!api) return;
+      rpcAbort = new AbortController();
+      stopRpc = onWorkspaceUpdated(api.events, () => currentLocation().directory, () => {
+        snapshotRequests.invalidate();
+        evidenceRequests.invalidate();
+        void refresh();
+      }, rpcEventOptions(context, rpcAbort.signal));
+    };
+    const queueRehydrate = (() => {
+      let queued = false;
+      return () => {
+        if (queued) return;
+        queued = true;
+        queueMicrotask(() => { queued = false; void rehydrate(); });
+      };
+    })();
+    const rehydrate = async () => {
+      const currentGeneration = ++generation;
+      snapshotRequests.invalidate();
+      evidenceRequests.invalidate();
+      rehydrateAbort?.abort();
+      rehydrateAbort = new AbortController();
+      nativeAbort?.abort();
+      nativeAbort = rehydrateAbort;
+      const isCurrent = () => currentGeneration === generation && !rehydrateAbort?.signal.aborted;
+      const [projects, active] = await Promise.allSettled([
+        context.data.project.sync(),
+        context.client.session.active({ signal: rehydrateAbort.signal }),
+      ]);
+      if (!isCurrent()) return;
+      if (projects.status === "rejected") setError(String(projects.reason));
+      if (active.status === "fulfilled") setActiveSessions(active.value);
+      else setError(String(active.reason));
+      try { await syncNativeSessions(isCurrent, nativeAbort.signal); }
+      catch (cause) { if (isCurrent()) setError(String(cause)); }
+      if (!isCurrent()) return;
+      await refresh(rehydrateAbort.signal);
+      if (!isCurrent()) return;
+      if (props.view === "evidence" || props.view === "workflow" || props.view === "architecture") {
+        const selected = activeSession();
+        if (selected) await refreshEvidence(selected);
+      }
+    };
+    const refreshLocationBinding = () => {
+      const directory = currentLocation().directory;
+      if (directory === observedDirectory) return false;
+      observedDirectory = directory;
+      generation++;
+      snapshotRequests.invalidate();
+      evidenceRequests.invalidate();
+      rehydrateAbort?.abort();
+      nativeAbort?.abort();
+      rpcAbort?.abort();
+      stopRpc?.();
+      subscribeRpc();
+      void rehydrate();
+      return true;
+    };
+    const invalidateFromHostEvent = (details: unknown) => {
+      const event = details as { type: string; data?: { sessionID?: string; form?: { sessionID?: string; info?: { sessionID?: string } } }; location?: { directory: string } };
+      const sessionID = event.data?.sessionID ?? event.data?.form?.sessionID ?? event.data?.form?.info?.sessionID;
+      if (sessionID) {
+        context.data.session.invalidate(sessionID);
+        context.data.session.permission.invalidate(sessionID);
+        context.data.session.form.invalidate(sessionID, event.location ?? currentLocation());
+      }
+      if (["session.created", "session.deleted", "session.updated", "session.status", "session.idle", "session.execution.started", "session.execution.succeeded", "session.execution.failed", "session.execution.interrupted", "permission.asked", "permission.replied", "form.created", "form.updated", "form.deleted", "form.replied", "form.cancelled"].includes(event.type)) {
+        queueRehydrate();
+      }
+    };
+    void rehydrate();
+    subscribeRpc();
+    const stopEvents = context.data.listen(({ details }) => {
+      if (refreshLocationBinding()) return;
+      if (details.type === "server.connected") {
+        setRpcConnected(true);
+        subscribeRpc();
+        void rehydrate();
+      } else {
+        if ((details as { type: string }).type === "server.disconnected") {
+          setRpcConnected(false);
+          generation++;
+          snapshotRequests.invalidate();
+          evidenceRequests.invalidate();
+          nativeAbort?.abort();
+          rpcAbort?.abort();
+          stopRpc?.();
+        } else invalidateFromHostEvent(details);
+      }
+    });
+    onCleanup(() => { generation++; snapshotRequests.invalidate(); evidenceRequests.invalidate(); rehydrateAbort?.abort(); nativeAbort?.abort(); rpcAbort?.abort(); stopRpc?.(); stopEvents(); });
+  });
+  const filteredProjects = () => (snapshot()?.projects ?? []).filter((project) =>
+    `${project.name ?? ""} ${project.directory}`.toLowerCase().includes(query().toLowerCase()));
+  const navigationOptions = () => {
+    const state = snapshot();
+    if (!state) return [];
+    const projects = filteredProjects();
+    const projectIDs = new Set(projects.map((project) => project.id));
+    const tasks = state.tasks.filter((task) => projectIDs.has(task.projectID));
+    const sessions = workspaceSessions();
+    return [
+      ...projects.map((project) => ({ name: `Project · ${project.name ?? project.directory}`, description: project.directory, value: { type: "project", id: project.id } })),
+      ...tasks.map((task) => ({ name: `Task · ${task.title} [${task.status}]`, description: task.directory ?? task.branch ?? task.id, value: { type: "task", id: task.id } })),
+      ...sessions.map((session) => ({ name: `Session · ${session.title}${session.attention ? ` [${session.attention} pending]` : ` [${session.status}]`}`, description: session.directory, value: { type: "session", id: session.id } })),
+    ];
+  };
+  const selectNavigation = (option: { value?: { type: string; id: string } } | null) => {
+    const selection = option?.value;
+    if (selection?.type === "session") void openSession(selection.id);
+    else if (selection?.type === "task") {
+      const task = snapshot()?.tasks.find((item) => item.id === selection.id);
+      const session = snapshot()?.sessions.find((item) => item.taskID === task?.id);
+      if (session) void openSession(session.id);
+      else setError("This task does not have an associated native session yet.");
+    } else if (selection?.type === "project") {
+      const project = snapshot()?.projects.find((item) => item.id === selection.id);
+      if (project) void worktree(project.id);
+    }
+  };
+  const openSession = async (sessionID: string) => {
+    if (!api) { context.ui.router.navigate({ type: "session", sessionID }); return; }
+    try { await api.open({ sessionID }); context.ui.router.navigate({ type: "session", sessionID }); }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+  };
+  const worktree = async (projectID: string) => {
+    const name = await context.ui.dialog.prompt({ title: "Create CTG worktree", placeholder: "feature-name" });
+    if (!name || !api) return;
+    try { const result = await api.createWorktree({ projectID, name }); context.ui.toast.show({ message: `Worktree created: ${context.ui.format.path(result.directory)}`, variant: "success" }); await refresh(); }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+  };
+
+  const evidenceSessions = () => workspaceSessions().filter((session) => !activeSession() || session.id === activeSession());
+  const readiness = () => renderDeliveryReadiness(deliveryEvidence());
+  const taskForSession = (sessionID: string) => snapshot()?.sessions.find((session) => session.id === sessionID)?.taskID;
+  const loadPullRequests = async (sessionID: string) => {
+    const taskID = taskForSession(sessionID);
+    if (!taskID) { setError("This session is not attached to a CTG task."); return; }
+    try {
+      const result = await pullRequestClient(context, sessionLocation).list({ sessionID, taskID });
+      setPullRequests((current) => ({ ...current, [taskID]: result.pullRequests }));
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+  };
+  const associatePullRequest = async (sessionID: string) => {
+    const taskID = taskForSession(sessionID);
+    if (!taskID) { setError("Associate a pull request from a session attached to a CTG task."); return; }
+    const answer = await context.ui.dialog.prompt({ title: "Associate GitHub pull request", placeholder: "Pull request number" });
+    if (!answer) return;
+    const number = Number(answer.trim());
+    if (!Number.isSafeInteger(number) || number < 1) { setError("Enter a positive pull request number."); return; }
+    try {
+      const result = await pullRequestClient(context, sessionLocation).associate({ sessionID, taskID, number });
+      setPullRequests((current) => ({ ...current, [taskID]: [...(current[taskID] ?? []).filter((item) => item.number !== number), result.pullRequest] }));
+      setError("");
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+  };
+  const refreshPullRequest = async (sessionID: string, taskID: string, number: number) => {
+    try {
+      const result = await pullRequestClient(context, sessionLocation).refresh({ sessionID, taskID, number });
+      setPullRequests((current) => ({ ...current, [taskID]: (current[taskID] ?? []).map((item) => item.number === number ? result.pullRequest : item) }));
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+  };
+  const refreshEvidence = async (sessionID: string) => {
+    if (!api) return;
+    const request = evidenceRequests.begin();
+    const signal = request.signal;
+    const [delivery, review] = await Promise.allSettled([
+      api.delivery({ sessionID }, signal),
+      api.review({ sessionID }, signal),
+    ]);
+    if (!request.isCurrent() || activeSession() !== sessionID) return;
+    setDeliveryEvidence(delivery.status === "fulfilled" ? delivery.value : { status: "invalid", error: String(delivery.reason) });
+    setReviewEvidence(review.status === "fulfilled" ? review.value : { error: String(review.reason) });
+  };
+  onMount(() => {
+    if (["evidence", "workflow", "architecture"].includes(props.view) && activeSession()) void refreshEvidence(activeSession()!);
+  });
+  return <box flexDirection="column" padding={1}>
+    <text fg={context.theme.text.feedback.warning.base}>CARTHAGENT · {props.view.toUpperCase()}</text>
+    <text fg={context.theme.text.muted}>CTG workspace tasks and native sessions associated with its projects.</text>
+    <box flexDirection="row" gap={1}>
+      <text fg={context.theme.text.action.secondary.base}>Filter:</text>
+      <input placeholder="project name or path" value={query()} onInput={setQuery} />
+      <text fg={context.theme.text.action.primary.base} on:click={() => void refresh()}>↻ Refresh</text>
+    </box>
+    <Show when={error()}><text fg={context.theme.text.feedback.error.base}>{error()}</text></Show>
+    <Show when={!rpcConnected()}><text fg={context.theme.text.feedback.warning.base}>Workspace RPC disconnected · cached view may be stale; waiting for native reconnect</text></Show>
+    <Show when={activeSession()}>{(active) => <box flexDirection="column" marginTop={1}>
+      <text fg={context.theme.text.action.primary.base}>Selected native session</text>
+      <For each={api ? snapshot()?.sessions.filter((session) => session.id === active()) ?? [] : localSessions().filter((session) => session.id === active())}>{(session) =>
+        <box flexDirection="column">
+          <text fg={context.theme.text.base}>{session.title}</text>
+          <Show when={api}>
+            <text fg={context.theme.text.action.secondary.base} on:click={() => void api?.delivery({ sessionID: active() }).then((value: unknown) => context.ui.dialog.alert({ title: "Observed delivery evidence", message: JSON.stringify(value ?? { status: "none" }, null, 2) })).catch((cause: unknown) => setError(String(cause)))}>View delivery evidence</text>
+            <text fg={context.theme.text.action.secondary.base} on:click={() => void api?.review({ sessionID: active() }).then((value) => context.ui.dialog.alert({ title: "Review status", message: `${value.status}${value.summary ? `\n\n${value.summary}` : ""}` })).catch((cause: unknown) => setError(String(cause)))}>View review status</text>
+          </Show>
+        </box>}</For>
+      <Show when={taskForSession(active())}>
+        <text fg={context.theme.text.action.primary.base}>Task pull requests · GitHub is queried only by explicit actions</text>
+        <text fg={context.theme.text.action.secondary.base} on:click={() => void loadPullRequests(active())}>Load cached pull requests</text>
+        <text fg={context.theme.text.action.secondary.base} on:click={() => void associatePullRequest(active())}>+ Associate pull request…</text>
+        <For each={pullRequests()[taskForSession(active())!] ?? []}>{(pr) => <box flexDirection="column">
+          <text fg={context.theme.text.base}>#{pr.number} · {pr.state}{pr.draft ? " · draft" : ""} · checks {pr.checks} · review {pr.review} · {pr.source}</text>
+          <text fg={context.theme.text.muted}>{pr.headRef} → {pr.baseRef} · {pr.head.slice(0, 10)} · updated {pr.updatedAt}</text>
+          <text fg={context.theme.text.action.secondary.base} on:click={() => void refreshPullRequest(active(), pr.taskID, pr.number)}>↻ Refresh #{pr.number} from GitHub</text>
+        </box>}</For>
+      </Show>
+    </box>}</Show>
+    <Show when={snapshot()} fallback={<text fg={context.theme.text.faint}>{error() || "Loading local workspace…"}</text>}>
+      <Show when={props.view === "workflow"}>
+        <text fg={context.theme.text.action.primary.base}>Authoritative delivery workflow · {deliveryEvidence()?.status ?? "select a session"}</text>
+        <text fg={readiness().gate === "open" ? context.theme.text.feedback.success.base : context.theme.text.feedback.warning.base}>{readiness().label} · finish gate {readiness().gate}</text>
+        <For each={readiness().sections}>{(section) => <text fg={context.theme.text.feedback.warning.base}>Incomplete DTO section · {section}</text>}</For>
+        <For each={readiness().receipts}>{(receipt) => <text fg={context.theme.text.feedback.warning.base}>{receipt}</text>}</For>
+        <Show when={deliveryEvidence()?.workflow} fallback={<text fg={context.theme.text.faint}>Select a session with a delivery report to load workflow nodes, edges, and step receipts.</text>}>
+          <text fg={context.theme.text.muted}>{deliveryEvidence()?.workflow?.semantics}</text>
+          <For each={deliveryEvidence()?.workflow?.nodes ?? []}>{(node) => <text fg={node.status === "failed" || node.status === "blocked" ? context.theme.text.feedback.error.base : node.status === "complete" || node.status === "passed" ? context.theme.text.feedback.success.base : context.theme.text.base}>[{node.status}] {node.title} · {node.type}{node.step ? ` · step ${node.step}` : ""} · checks: {node.checks.join(", ") || "none"}</text>}</For>
+          <For each={deliveryEvidence()?.workflow?.edges ?? []}>{(edge) => <text fg={context.theme.text.muted}>{edge.from} → {edge.to} · {edge.label ?? edge.kind}{edge.when ? ` · when ${edge.when}` : ""}</text>}</For>
+        </Show>
+        <text fg={context.theme.text.action.secondary.base} on:click={() => activeSession() && void refreshEvidence(activeSession()!)}>↻ Refresh delivery workflow</text>
+      </Show>
+      <Show when={props.view === "architecture"}>
+        <text fg={context.theme.text.action.primary.base}>Delivery architecture · {deliveryEvidence()?.status ?? "select a session"}</text>
+        <text fg={context.theme.text.feedback.warning.base}>{readiness().label} · finish gate {readiness().gate}</text>
+        <For each={readiness().sections}>{(section) => <text fg={context.theme.text.feedback.warning.base}>Incomplete DTO section · {section}</text>}</For>
+        <For each={readiness().receipts}>{(receipt) => <text fg={context.theme.text.feedback.warning.base}>{receipt}</text>}</For>
+        <Show when={deliveryEvidence()?.architecture} fallback={<text fg={context.theme.text.faint}>Select a session with a delivery report to load authored architecture nodes, edges, and ports.</text>}>
+          <For each={deliveryEvidence()?.architecture?.nodes ?? []}>{(node) => <text fg={context.theme.text.base}>◆ {node.title} · {node.type ?? "component"}{node.layer ? ` · layer ${node.layer}` : ""}{node.status ? ` · ${node.status}` : ""}</text>}</For>
+          <For each={deliveryEvidence()?.architecture?.edges ?? []}>{(edge) => <text fg={context.theme.text.muted}>{edge.from} → {edge.to} · {edge.label ?? edge.kind}</text>}</For>
+          <For each={deliveryEvidence()?.architecture?.ports ?? []}>{(port) => <text fg={context.theme.text.action.secondary.base}>⇄ {port.id} · {port.owner} via {port.adapter} · root {port.compositionRoot}{port.integrationAssertion ? ` · verifies ${port.integrationAssertion}` : ""}</text>}</For>
+        </Show>
+        <text fg={context.theme.text.action.secondary.base} on:click={() => activeSession() && void refreshEvidence(activeSession()!)}>↻ Refresh delivery architecture</text>
+      </Show>
+      <Show when={props.view === "evidence"}>
+        <text fg={context.theme.text.action.primary.base}>Observed delivery evidence</text>
+        <For each={evidenceSessions()}>{(session) => <text fg={context.theme.text.muted}>{session.title} · {session.status} · {session.directory}</text>}</For>
+        <Show when={evidenceSessions().length === 0}><text fg={context.theme.text.faint}>No matching workspace session has recorded evidence.</text></Show>
+        <Show when={activeSession()}>
+          <text fg={context.theme.text.action.secondary.base} on:click={() => void refreshEvidence(activeSession()!)}>↻ Refresh selected session evidence</text>
+          <text fg={context.theme.text.action.primary.base}>Delivery receipt</text>
+          <Show when={deliveryEvidence()} fallback={<text fg={context.theme.text.faint}>Loading delivery receipt…</text>}>
+            <text fg={context.theme.text.base}>Status: {deliveryEvidence()?.status} · {deliveryEvidence()?.freshness ?? "freshness unavailable"} · revision {deliveryEvidence()?.revision ?? "—"} · run {deliveryEvidence()?.runId ?? "—"}</text>
+            <text fg={readiness().gate === "open" ? context.theme.text.feedback.success.base : readiness().gate === "locked" ? context.theme.text.feedback.warning.base : context.theme.text.muted}>{readiness().label} · finish gate {readiness().gate} · {readiness().coverageLabel}</text>
+            <For each={readiness().sections}>{(section) => <text fg={context.theme.text.muted}>Returned DTO section · {section}</text>}</For>
+            <For each={readiness().receipts}>{(receipt) => <text fg={context.theme.text.feedback.warning.base}>{receipt}</text>}</For>
+            <Show when={deliveryEvidence()?.plan}>{(plan) => <box flexDirection="column">
+              <text fg={context.theme.text.action.primary.base}>Goal: {plan().goal}</text>
+              <Show when={deliveryEvidence()?.truncation?.steps}>{(scope) => <text fg={context.theme.text.muted}>Steps: {scope().returned} of {scope().total} returned</text>}</Show>
+              <For each={plan().steps}>{(step) => <text fg={step.status === "completed" ? context.theme.text.feedback.success.base : context.theme.text.base}>[{step.status}] {step.id} · {step.title}{step.dependsOn.length ? ` · after ${step.dependsOn.join(", ")}` : ""}</text>}</For>
+              <Show when={deliveryEvidence()?.truncation?.checks}>{(scope) => <text fg={context.theme.text.muted}>Checks: {scope().returned} of {scope().total} returned</text>}</Show>
+              <For each={deliveryEvidence()?.evidence ?? []}>{(item) => <text fg={item.status === "fresh" ? context.theme.text.feedback.success.base : item.status === "failed" || item.status === "stale" ? context.theme.text.feedback.error.base : context.theme.text.feedback.warning.base}>Receipt {item.id}: {item.status}{item.code !== undefined ? ` · exit ${item.code}` : ""}{item.filename ? ` · ${item.filename}` : ""}</text>}</For>
+            </box>}</Show>
+          </Show>
+          <text fg={context.theme.text.action.primary.base}>Review receipt</text>
+          <Show when={reviewEvidence()} fallback={<text fg={context.theme.text.faint}>Loading review receipt…</text>}>
+            <text fg={context.theme.text.muted}>{String((reviewEvidence() as { status?: string; summary?: string } | undefined)?.status ?? "unavailable")}{(reviewEvidence() as { summary?: string } | undefined)?.summary ? ` · ${(reviewEvidence() as { summary: string }).summary}` : ""}</text>
+          </Show>
+        </Show>
+      </Show>
+      <select options={navigationOptions()} onSelect={(_index, option) => selectNavigation(option)} focused />
+      <For each={filteredProjects()}>{(project) => <box flexDirection="column" marginTop={1}>
+        <text fg={context.theme.text.action.primary.base}>◆ {project.name ?? project.directory}</text>
+        <text fg={context.theme.text.muted}>{context.ui.format.path(project.directory)}</text>
+        <text fg={context.theme.text.action.secondary.base} on:click={() => void worktree(project.id)}>+ Create worktree</text>
+        <For each={snapshot()?.tasks.filter((task) => task.projectID === project.id)}>{(task) => <box flexDirection="column" paddingLeft={2}>
+          <text fg={task.attention ? context.theme.text.feedback.warning.base : context.theme.text.base}>{task.attention ? "! " : "· "}{task.title}  [{task.status}]</text>
+         <For each={snapshot()?.sessions.filter((session) => session.taskID === task.id)}>{(session) =>
+            <text fg={context.theme.text.muted}>  ↳ {session.title} · {session.status}</text>}</For>
+        </box>}</For>
+      </box>}</For>
+    </Show>
+    <Show when={snapshot()}>
+      <text fg={context.theme.text.action.primary.base}>Workspace native sessions</text>
+      <For each={workspaceSessions()}>{(session) => <text fg={session.attention ? context.theme.text.feedback.warning.base : context.theme.text.action.secondary.base} on:click={() => void openSession(session.id)}>{session.attention ? "! " : "· "}{session.title} [{session.attention ? `${session.attention} pending` : session.status}] · {session.directory}</text>}</For>
+    </Show>
+    <Show when={!snapshot()}>
+      <text fg={context.theme.text.action.primary.base}>Local Carthagent sessions</text>
+      <For each={localSessions().filter((session) => !query() || `${session.title ?? ""} ${session.id} ${session.location.directory}`.toLowerCase().includes(query().toLowerCase()))}>{(session) => <text fg={context.theme.text.action.secondary.base} on:click={() => context.ui.router.navigate({ type: "session", sessionID: session.id })}>· {session.title ?? session.id} [{context.data.session.status(session.id)}]</text>}</For>
+    </Show>
+    <text fg={context.theme.text.faint}>Keyboard: use /ctg-open to search sessions; /ctg-worktree creates a worktree; /ctg-task starts a task.</text>
+  </box>;
+}

package/plugins/carthagent/src/voyages-rpc.ts

@@ -0,0 +1,64 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+export const voyagesSlots = ['hairStyle', 'hat', 'shirt', 'bottoms', 'shoes', 'pet', 'hull', 'sail', 'setting'] as const;
+export const voyagesAppearance = { skin: ['warm', 'light', 'deep', 'tan'], hair: ['dark', 'silver', 'copper'], pattern: ['stripes', 'plain'] } as const;
+export type VoyagesSlot = typeof voyagesSlots[number];
+export type VoyagesProfile = {
+  version: number; name: string; shipName: string; coins: number; totalXp: number; level: number;
+  xpIntoLevel: number; xpForLevel: number; km: number; weeklyKm: number;
+  config: Record<VoyagesSlot, string> & { skin: string; hair: string; pattern: string }; owned: string[];
+};
+export type VoyagesItem = { item: string; name: string; slot: VoyagesSlot; itemKey: string; price: number | null; requiresPurchase: boolean; available: boolean; eligible: boolean; reason: string | null };
+export type VoyagesQuote = { id: string; item: string; price: number; expiresAt: string };
+export type VoyagesPending = { quoteId: string; item: string; price: number };
+export type VoyagesSnapshot = { profile: VoyagesProfile; items: VoyagesItem[]; pending?: VoyagesPending };
+
+const text = { type: 'string', minLength: 1, maxLength: 128 } as const;
+// Native Effect JSON-schema conversion does not support arbitrary patterns.
+// The server validates equipment key syntax before forwarding mutations.
+const key = { type: 'string', minLength: 1, maxLength: 64 } as const;
+const integer = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER } as const;
+const version = { ...integer, minimum: 1 } as const;
+const slot = { type: 'string', enum: voyagesSlots } as const;
+const skin = { type: 'string', enum: voyagesAppearance.skin } as const;
+const hair = { type: 'string', enum: voyagesAppearance.hair } as const;
+const pattern = { type: 'string', enum: voyagesAppearance.pattern } as const;
+const name = { type: 'string', minLength: 1, maxLength: 20 } as const;
+const shipName = { type: 'string', minLength: 1, maxLength: 28 } as const;
+const config = {
+  type: 'object', properties: { hairStyle: key, hat: key, shirt: key, bottoms: key, shoes: key, pet: key, hull: key, sail: key, setting: key, skin, hair, pattern },
+  required: [...voyagesSlots, 'skin', 'hair', 'pattern'], additionalProperties: false,
+} as const;
+const profile = {
+  type: 'object', properties: { version, name, shipName, coins: integer, totalXp: integer, level: version, xpIntoLevel: integer, xpForLevel: version, km: { type: 'number', minimum: 0 }, weeklyKm: { type: 'number', minimum: 0 }, config, owned: { type: 'array', maxItems: 10000, items: text, uniqueItems: true } },
+  required: ['version', 'name', 'shipName', 'coins', 'totalXp', 'level', 'xpIntoLevel', 'xpForLevel', 'km', 'weeklyKm', 'config', 'owned'], additionalProperties: false,
+} as const;
+const item = {
+  type: 'object', properties: { item: text, name: text, slot, itemKey: key, price: { ...integer, type: ['integer', 'null'] }, requiresPurchase: { type: 'boolean' }, available: { type: 'boolean' }, eligible: { type: 'boolean' }, reason: { type: ['string', 'null'], maxLength: 128 } },
+  required: ['item', 'name', 'slot', 'itemKey', 'price', 'requiresPurchase', 'available', 'eligible', 'reason'], additionalProperties: false,
+} as const;
+const pending = { type: 'object', properties: { quoteId: text, item: text, price: integer }, required: ['quoteId', 'item', 'price'], additionalProperties: false } as const;
+const quote = { type: 'object', properties: { id: text, item: text, price: integer, expiresAt: { type: 'string', format: 'date-time' } }, required: ['id', 'item', 'price', 'expiresAt'], additionalProperties: false } as const;
+const errors = { voyagesError: { type: 'object', properties: { code: text, status: { type: 'integer', minimum: 0, maximum: 599 }, uncertain: { type: 'boolean' } }, required: ['code', 'status', 'uncertain'], additionalProperties: false } } as const;
+const empty = { type: 'object', additionalProperties: false } as const;
+const selection = { type: 'object', properties: { slot, item: key }, required: ['slot', 'item'], additionalProperties: false } as const;
+const profileResult = { type: 'object', properties: { profile }, required: ['profile'], additionalProperties: false } as const;
+const receipt = { type: 'object', properties: { receiptId: text, item: text, price: integer }, required: ['receiptId', 'item', 'price'], additionalProperties: false } as const;
+const reward = { type: 'object', properties: { id: text, runId: text, policyVersion: text, coins: integer, xp: integer, km: integer, awardedAt: text, basis: text }, required: ['id', 'runId', 'policyVersion', 'coins', 'xp', 'km', 'awardedAt', 'basis'], additionalProperties: false } as const;
+const rewardPreview = { type: 'object', properties: { runId: text, snapshot: text, coins: integer, xp: integer, km: integer, dailyLimit: integer }, required: ['runId', 'snapshot', 'coins', 'xp', 'km', 'dailyLimit'], additionalProperties: false } as const;
+
+/** Authenticated server-only Voyages boundary. Confirmation belongs to the UI. */
+export const Voyages = Rpc.define({
+  id: 'carthagent.voyages',
+  methods: {
+    previewReward: { errors, input: { type: 'object', properties: { sessionID: text }, required: ['sessionID'], additionalProperties: false }, output: rewardPreview },
+    claimReward: { errors, input: { type: 'object', properties: { sessionID: text, runId: text, snapshot: text }, required: ['sessionID', 'runId', 'snapshot'], additionalProperties: false }, output: { type: 'object', properties: { reward, replayed: { type: 'boolean' } }, required: ['reward', 'replayed'], additionalProperties: false } },
+    snapshot: { errors, input: empty, output: { type: 'object', properties: { profile, items: { type: 'array', maxItems: 10000, items: item }, pending }, required: ['profile', 'items'], additionalProperties: false } },
+    customize: { errors, input: { type: 'object', properties: { version, name, shipName, skin, hair, pattern }, required: ['version'], additionalProperties: false }, output: profileResult },
+    equip: { errors, input: { ...selection, properties: { ...selection.properties, version }, required: ['version', 'slot', 'item'] }, output: profileResult },
+    quote: { errors, input: selection, output: { type: 'object', properties: { quote }, required: ['quote'], additionalProperties: false } },
+    purchase: { errors, input: { type: 'object', properties: { quoteId: text }, required: ['quoteId'], additionalProperties: false }, output: receipt },
+    retryPurchase: { errors, input: { type: 'object', properties: { quoteId: text }, required: ['quoteId'], additionalProperties: false }, output: receipt },
+  },
+  events: {},
+});

package/plugins/carthagent/src/workspace-rpc.ts

@@ -131,3 +131,39 @@ export interface WorkspaceSnapshot {
   tasks: Array<{ id: string; projectID: string; title: string; status: string; attention?: boolean; directory?: string; branch?: string }>;
   sessions: Array<{ id: string; taskID?: string; projectID?: string; title: string; status: string; updatedAt?: string; directory: string }>;
 }
+
+export interface WorkspaceDelivery {
+  status: string;
+  freshness?: "current" | "stale";
+  completion?: "ready" | "incomplete";
+  gate?: "locked" | "open";
+  runId?: string;
+  revision?: number;
+  fingerprint?: string;
+  truncation?: Record<string, { returned: number; total: number }>;
+  plan?: {
+    goal: string;
+    verification: string;
+    acceptance: Array<{ requirement: string; checks: string[] }>;
+    artifacts: string[];
+    outputs: string[];
+    assumptions: string[];
+    checks: Array<{ id: string; kind: string; argv: string[]; timeoutSeconds: number }>;
+    steps: Array<{ id: string; title: string; status: string; dependsOn: string[]; checks: string[] }>;
+    scenarios: Array<{ id: string; requirement: string; kind: string; path: string[]; checks: string[]; input: string; expected: string; assertion: string }>;
+    risks: Array<{ id: string; description: string; status: string; blocking: boolean; evidence: string }>;
+  };
+  workflow?: {
+    authored: boolean;
+    semantics: string;
+    nodes: Array<{ id: string; title: string; type: string; status: string; step?: string; requirements: string[]; components: string[]; checks: string[]; inputs: string[]; artifacts: string[]; effects: string[]; condition?: string }>;
+    edges: Array<{ from: string; to: string; kind: string; label?: string; when?: string; stop?: string; maxAttempts?: number }>;
+  };
+  architecture?: {
+    nodes: Array<{ id: string; title: string; type?: string; status?: string; layer?: string; excludes?: string[]; requirements?: string[] }>;
+    edges: Array<{ from: string; to: string; kind: string; label?: string }>;
+    ports: Array<{ id: string; owner: string; adapter: string; compositionRoot: string; input: string; output: string; errors: string; injection: string; testDouble: string; integrationAssertion: string }>;
+  };
+  evidence?: Array<{ id: string; status: "pending" | "failed" | "fresh" | "stale"; executedRevision?: number; code?: number; filename?: string }>;
+  error?: string;
+}

package/plugins/carthagent/tests/commands.test.ts

@@ -0,0 +1,107 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { COMMANDS, matchCommand, NATIVE_COMMAND_COLLISIONS, resolveCommand } from "../src/ui/commands.js";
+import { readFile } from "node:fs/promises";
+import { parseThemeDocument } from "@opencode/theme/tui";
+import { cliConfigDirectory, cliConfigPath, readCliConfig, writeNativeTheme } from "../src/ui/host-state.js";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { provisionNativeThemes } from "../src/ui/theme-provision.mjs";
+
+test("Carthagent command manifest resolves visible CTG commands", () => {
+  assert.equal(resolveCommand("/help")?.id, "help");
+  assert.equal(resolveCommand("/ctg-help")?.id, "help");
+  assert.deepEqual(COMMANDS.find((item) => item.id === "help")?.aliases, ["ctg-help"]);
+  assert.equal(COMMANDS.find((item) => item.id === "help")?.submitSlash, true);
+  assert.equal(resolveCommand("/review")?.id, "review");
+  assert.equal(resolveCommand("/review-mode")?.id, "review");
+  for (const name of ["workflow", "architecture", "evidence"]) assert.equal(resolveCommand(name)?.hidden, undefined);
+  for (const name of ["model", "compact", "autocompact", "abort", "clear"]) assert.equal(resolveCommand(name)?.id, name);
+  assert.deepEqual(matchCommand("/arch").map((item) => item.name), ["architecture", "archive"]);
+  assert.deepEqual(matchCommand("/rev status"), []);
+  for (const name of ["login", "account", "usage", "billing", "logout-cloud", "archive", "demo", "voyages", "quests"]) {
+    assert.ok(resolveCommand(`/${name}`), `/${name} must resolve to a registered handler`);
+  }
+  assert.equal(resolveCommand("/cloud")?.id, "account");
+  assert.equal(resolveCommand("/auth")?.id, "login");
+  assert.match(resolveCommand("/voyages")!.description, /daily quests/);
+  assert.match(resolveCommand("/quests")!.description, /separate explicit consent/);
+});
+
+test("manifest prevents collisions with native OpenCode slash commands", () => {
+  for (const name of NATIVE_COMMAND_COLLISIONS) assert.equal(COMMANDS.some((item) => item.name === name || item.aliases?.includes(name)), false, name);
+  assert.equal(NATIVE_COMMAND_COLLISIONS.includes("help" as typeof NATIVE_COMMAND_COLLISIONS[number]), false);
+  assert.deepEqual(COMMANDS.filter((item) => ["model", "compact", "abort", "resume"].includes(item.name)).map((item) => item.name).sort(), ["abort", "compact", "model", "resume"]);
+});
+
+test("theme provisioning installs the startup default through its launcher-facing export", async () => {
+  const { provisionDefaultNativeTheme } = await import("../src/ui/theme-provision.mjs");
+  const directory = await mkdtemp(join(tmpdir(), "ctg-default-theme-"));
+  try {
+    const result = await provisionDefaultNativeTheme(directory);
+    assert.ok(result.installed.includes("carthage"));
+    const theme = parseThemeDocument(JSON.parse(await readFile(join(result.directory, "carthage.json"), "utf8")), "carthage");
+    assert.equal(theme.dark.hue.yellow[400], "#d5af66");
+  } finally { await rm(directory, { recursive: true, force: true }); }
+});
+
+test("startup theme provisioning covers compatibility themes and preserves host/user themes", async () => {
+  const { provisionDefaultNativeTheme } = await import("../src/ui/theme-provision.mjs");
+  const directory = await mkdtemp(join(tmpdir(), "ctg-startup-themes-"));
+  try {
+    await mkdir(join(directory, "themes"), { recursive: true });
+    await writeFile(join(directory, "themes", "forest.json"), '{"userOwned":true}');
+    const result = await provisionDefaultNativeTheme(directory);
+    assert.ok(result.installed.includes("carthage"));
+    assert.ok(result.installed.includes("forest") === false);
+    assert.ok(result.conflicts.includes("forest"));
+    assert.ok(result.installed.includes("opencode") === false);
+    assert.ok(result.installed.includes("tokyonight") === false);
+    assert.deepEqual(JSON.parse(await readFile(join(directory, "themes", "forest.json"), "utf8")), { userOwned: true });
+  } finally { await rm(directory, { recursive: true, force: true }); }
+});
+
+test("Carthage theme validates against the OpenCode V2 theme schema and resolver", async () => {
+  const raw = JSON.parse(await readFile(new URL("../themes/carthage.json", import.meta.url), "utf8"));
+  const resolved = parseThemeDocument(raw, "carthage");
+  assert.ok(resolved.dark?.hue.yellow);
+  assert.equal(resolved.base.categorical?.length, 5);
+});
+
+test("native CLI theme write preserves unrelated cli.json settings", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "ctg-cli-config-"));
+  const path = join(directory, "cli.json");
+  try {
+    await writeFile(path, JSON.stringify({ theme: { name: "opencode", mode: "dark" }, session: { thinking: "show" }, custom: true }));
+    await writeNativeTheme(path, "carthage");
+    const config = await readCliConfig(path);
+    assert.deepEqual(config.theme, { name: "carthage", mode: "dark" });
+    assert.deepEqual(config.session, { thinking: "show" });
+    assert.equal(config.custom, true);
+    assert.equal(cliConfigPath({ XDG_CONFIG_HOME: "/tmp/profile" }, "/home/test"), join("/tmp/profile", "opencode", "cli.json"));
+    assert.equal(cliConfigDirectory({ OPENCODE_CONFIG_DIR: "/tmp/opencode-profile" }), "/tmp/opencode-profile");
+    assert.equal(cliConfigDirectory({ XDG_CONFIG_HOME: "/tmp/profile" }, "/home/test"), join("/tmp/profile", "opencode"));
+  } finally { await rm(directory, { recursive: true, force: true }); }
+});
+
+test("native theme provisioning converts legacy palettes inside the selected OpenCode profile", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "ctg-native-themes-"));
+  const themeDirectory = join(directory, "themes");
+  try {
+    await mkdir(themeDirectory, { recursive: true });
+    await writeFile(join(themeDirectory, "user-theme.json"), '{"custom":true}');
+    const result = await provisionNativeThemes(directory, ["carthage", "nebula"]);
+    assert.deepEqual(result.installed.sort(), ["carthage", "nebula"]);
+    assert.deepEqual(JSON.parse(await readFile(join(themeDirectory, "user-theme.json"), "utf8")), { custom: true });
+    const carthage = parseThemeDocument(JSON.parse(await readFile(join(themeDirectory, "carthage.json"), "utf8")), "carthage");
+    const nebula = parseThemeDocument(JSON.parse(await readFile(join(themeDirectory, "nebula.json"), "utf8")), "nebula");
+    assert.equal(carthage.dark.hue.yellow[400], "#d5af66");
+    assert.equal(carthage.dark.hue.yellow[300], "#e6c480");
+    assert.ok(nebula.dark.hue.blue[400]);
+    const again = await provisionNativeThemes(directory, ["carthage"]);
+    assert.deepEqual(again.installed, []);
+    await writeFile(join(themeDirectory, "forest.json"), '{"userOwned":true}');
+    await assert.rejects(provisionNativeThemes(directory, ["forest"]), /Refusing to replace/);
+  } finally { await rm(directory, { recursive: true, force: true }); }
+});