carthagent 0.0.0-stage → 1.0.7

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

@@ -0,0 +1,349 @@
+import type { Context } from '@opencode/plugin/promise/plugin';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { completionIssues, evidenceFresh, fingerprint, reviewFresh, requiresReview, validatePlan } from '../../../../lib/delivery.mjs';
+import { planningView } from '../../../../lib/planning-view.mjs';
+import { planningStatus } from '../../../../lib/planning.mjs';
+import { localReviewSnapshot, startReview } from '../../../../lib/opencode/review.mjs';
+import { createTask, listTasks } from '../../../../lib/opencode/workspace.mjs';
+import { assertActiveReport, activeReportPath } from '../../../../lib/workspace.mjs';
+import { Workspace, type WorkspaceSnapshot } from '../workspace-rpc';
+
+type TaskRecord = { id: string; task: string; sessionID: string; worktree: string; status: string; branch?: string };
+type OperationRecord = { id: string; task: string; sessionID?: string; worktree?: string; status: string; branch?: string };
+type TaskState = { tasks: TaskRecord[]; operations: OperationRecord[] };
+type NativeSession = Awaited<ReturnType<Context['session']['get']>>;
+type JsonRecord = Record<string, unknown>;
+type DeliveryCheck = JsonRecord & { id: string; kind?: string; argv?: string[] };
+type DeliveryStep = string | (JsonRecord & { id: string; title: string; dependsOn: string[]; checks: string[] });
+type DeliveryAcceptance = JsonRecord & { requirement: string; checks: string[] };
+type DeliveryPlan = JsonRecord & {
+  goal: string; artifacts: string[]; outputs?: string[]; assumptions?: string[]; steps: DeliveryStep[];
+  acceptance: DeliveryAcceptance[]; checks: DeliveryCheck[]; design?: JsonRecord; verification?: string;
+};
+type DeliveryState = { runId: string; revision: number; status?: string; plan: DeliveryPlan; evidence?: Record<string, JsonRecord>; stepStatus?: Record<string, string> };
+
+const MAX_TEXT = 4000;
+const boundedText = (value: unknown, max = MAX_TEXT) => typeof value === 'string' ? value.slice(0, max) : '';
+const asRecord = (value: unknown): JsonRecord => value && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : {};
+const boundedList = <T>(value: unknown, max: number, project: (item: unknown, index: number) => T): T[] => Array.isArray(value) ? value.slice(0, max).map(project) : [];
+const listLength = (value: unknown) => Array.isArray(value) ? value.length : 0;
+
+function reportFor(directory: string, sessionID: string) {
+  try {
+    const path = activeReportPath(directory);
+    if (!path || !existsSync(path)) return { status: 'unavailable' } as const;
+    const reportRelative = relative(directory, path).split(sep);
+    if (reportRelative.length !== 4 || reportRelative[0] !== '.harness' || reportRelative[1] !== sessionID || reportRelative[3] !== 'report.json') return { status: 'unavailable' } as const;
+    let cursor = resolve(directory);
+    for (const part of reportRelative) {
+      cursor = join(cursor, part);
+      const info = lstatSync(cursor);
+      if (info.isSymbolicLink()) return { status: 'invalid' } as const;
+    }
+    if (!lstatSync(path).isFile()) return { status: 'invalid' } as const;
+    if (statSync(path).size > 1024 * 1024) return { status: 'invalid' } as const;
+    const state = JSON.parse(readFileSync(path, 'utf8')) as DeliveryState;
+    if (!state || typeof state !== 'object' || !state.plan || typeof state.runId !== 'string' || !state.runId || state.runId.length > 128 || reportRelative[2] !== state.runId || !Number.isSafeInteger(state.revision) || state.revision < 1 || !Array.isArray(state.plan.checks)) return { status: 'invalid' } as const;
+    if (state.status !== undefined && !['implementing', 'verifying', 'verified', 'blocked'].includes(state.status)) return { status: 'invalid' } as const;
+    if (state.evidence !== undefined && (!state.evidence || typeof state.evidence !== 'object' || Array.isArray(state.evidence) || Object.keys(state.evidence).length > 20000)) return { status: 'invalid' } as const;
+    validatePlan(state.plan, directory);
+    if (Object.keys(state.evidence ?? {}).some(id => !state.plan.checks?.some(check => check.id === id))) return { status: 'invalid' } as const;
+    for (const check of state.plan.checks) {
+      const receipt = state.evidence?.[check.id];
+      if (receipt && (typeof receipt.passed !== 'boolean' || typeof receipt.fingerprint !== 'string' || receipt.runId !== undefined && typeof receipt.runId !== 'string' || receipt.revision !== undefined && !Number.isSafeInteger(receipt.revision) || receipt.checkDigest !== undefined && typeof receipt.checkDigest !== 'string' || receipt.code !== undefined && !Number.isSafeInteger(receipt.code) || receipt.durationMs !== undefined && !Number.isFinite(receipt.durationMs))) return { status: 'invalid' } as const;
+    }
+    assertActiveReport(directory, path);
+    const current = fingerprint(directory, ['.']);
+    if (!/^[a-f0-9]{64}$/.test(current)) return { status: 'invalid' } as const;
+    const view = planningView(state, current);
+    const workflowView = view.workflow as { authored?: boolean; semantics?: string; nodes?: JsonRecord[]; edges?: JsonRecord[] } | null;
+    const allEvidence = state.plan.checks.map(raw => {
+      const check = asRecord(raw) as DeliveryCheck;
+      const receipt = state.evidence?.[check.id];
+      const fresh = evidenceFresh(check, receipt, current, state);
+      const status = !receipt ? 'pending' : !receipt.passed ? 'failed' : fresh ? 'fresh' : 'stale';
+      const filename = typeof receipt?.logPath === 'string' && !receipt.logPath.split(/[\\/]/).includes('..') ? basename(receipt.logPath) : undefined;
+      return {
+        id: boundedText(check.id, 80), status,
+        ...(Number.isSafeInteger(receipt?.executedRevision) ? { executedRevision: receipt?.executedRevision as number } : {}),
+        ...(Number.isSafeInteger(receipt?.code) ? { code: receipt?.code as number } : {}),
+        ...(filename ? { filename: boundedText(filename, 160) } : {}),
+      };
+    });
+    const evidence = allEvidence.slice(0, 100);
+    const plan = {
+      goal: boundedText(state.plan.goal), verification: boundedText(state.plan.verification ?? 'required', 32),
+      acceptance: boundedList(state.plan.acceptance, 80, raw => { const item = asRecord(raw); return { requirement: boundedText(item.requirement), checks: boundedList(item.checks, 100, id => boundedText(id, 80)) }; }),
+      artifacts: boundedList(state.plan.artifacts, 40, item => boundedText(item, 240)),
+      outputs: boundedList(state.plan.outputs, 40, item => boundedText(item, 240)),
+      assumptions: boundedList(state.plan.assumptions, 40, item => boundedText(item)),
+      checks: boundedList(state.plan.checks, 100, raw => { const check = asRecord(raw); return { id: boundedText(check.id, 80), kind: boundedText(check.kind, 32), argv: boundedList(check.argv, 32, item => boundedText(item, 1000)), timeoutSeconds: Number.isSafeInteger(check.timeoutSeconds) ? check.timeoutSeconds as number : 0 }; }),
+      steps: boundedList(state.plan.steps, 40, (raw, index) => { const step = asRecord(raw); return {
+        id: boundedText(typeof raw === 'string' ? `legacy_${index + 1}` : step.id, 80),
+        title: boundedText(typeof raw === 'string' ? raw : step.title),
+        status: boundedText(state.stepStatus?.[`step${index}`] ?? 'pending', 32),
+        dependsOn: boundedList(typeof raw === 'string' ? [] : step.dependsOn, 40, item => boundedText(item, 80)),
+        checks: boundedList(typeof raw === 'string' ? [] : step.checks, 100, item => boundedText(item, 80)),
+      }; }),
+      scenarios: boundedList(asRecord(state.plan.design).scenarios, 80, raw => { const scenario = asRecord(raw); return { id: boundedText(scenario.id, 80), requirement: boundedText(scenario.requirement), kind: boundedText(scenario.kind, 32), path: boundedList(scenario.path, 40, item => boundedText(item, 80)), checks: boundedList(scenario.checks, 100, item => boundedText(item, 80)), input: boundedText(scenario.input), expected: boundedText(scenario.expected), assertion: boundedText(scenario.assertion) }; }),
+      risks: boundedList(asRecord(state.plan.design).risks, 80, raw => { const risk = asRecord(raw); return { id: boundedText(risk.id, 80), description: boundedText(risk.description), status: boundedText(risk.status, 32), blocking: risk.blocking === true, evidence: boundedText(risk.evidence) }; }),
+    };
+    const workflow = {
+      authored: workflowView?.authored === true,
+      semantics: boundedText(workflowView?.semantics, 1000),
+      nodes: boundedList(workflowView?.nodes, 100, raw => { const node = asRecord(raw); return {
+        id: boundedText(node.id, 80), title: boundedText(node.title), type: boundedText(node.type, 32), status: boundedText(node.status, 32),
+        ...(typeof node.step === 'string' ? { step: boundedText(node.step, 80) } : {}),
+        requirements: boundedList(node.requirements, 80, item => boundedText(item)), components: boundedList(node.components, 80, item => boundedText(item, 80)),
+        checks: boundedList(node.checks, 100, item => boundedText(item, 80)), inputs: boundedList(node.inputs, 80, item => boundedText(item)),
+        artifacts: boundedList(node.artifacts, 80, item => boundedText(item, 240)), effects: boundedList(node.effects, 10, item => boundedText(item, 32)),
+        ...(typeof node.condition === 'string' ? { condition: boundedText(node.condition) } : {}),
+      }; }),
+      edges: boundedList(workflowView?.edges, 200, raw => { const edge = asRecord(raw); return {
+        from: boundedText(edge.from, 80), to: boundedText(edge.to, 80), kind: boundedText(edge.kind, 32),
+        ...(typeof edge.label === 'string' ? { label: boundedText(edge.label) } : {}),
+        ...(typeof edge.when === 'string' ? { when: boundedText(edge.when) } : {}),
+        ...(typeof edge.stop === 'string' ? { stop: boundedText(edge.stop) } : {}),
+        ...(Number.isSafeInteger(edge.maxAttempts) ? { maxAttempts: edge.maxAttempts as number } : {}),
+      }; }),
+    };
+    const architecture = {
+      nodes: boundedList(view.architecture?.nodes, 80, raw => { const node = asRecord(raw); return { id: boundedText(node.id, 80), title: boundedText(node.title), layer: boundedText(node.layer, 32), excludes: boundedList(node.excludes, 30, item => boundedText(item)), requirements: boundedList(node.requirements, 80, item => boundedText(item)) }; }),
+      edges: boundedList(view.architecture?.edges, 200, raw => { const edge = asRecord(raw); return { from: boundedText(edge.from, 80), to: boundedText(edge.to, 80), kind: boundedText(edge.kind, 32) }; }),
+      ports: boundedList(view.architecture?.ports, 80, raw => { const port = asRecord(raw); return { id: boundedText(port.id, 80), owner: boundedText(port.owner, 80), adapter: boundedText(port.adapter, 80), compositionRoot: boundedText(port.compositionRoot, 80), input: boundedText(port.input), output: boundedText(port.output), errors: boundedText(port.errors), injection: boundedText(port.injection), testDouble: boundedText(port.testDouble), integrationAssertion: boundedText(port.integrationAssertion) }; }),
+    };
+    const gate = planningStatus(state, current);
+    const issues = completionIssues(state, directory, current);
+    const reviewRequired = requiresReview(state);
+    const reviewIsFresh = !reviewRequired || reviewFresh(state, current);
+    const isStale = allEvidence.some(item => item.status === 'stale') || reviewRequired && !reviewIsFresh;
+    const planningViewLocked = view.gate.locked;
+    const noCompletionIssues = !Object.values(issues).some(value => Array.isArray(value) && value.length > 0);
+    const allChecksFresh = allEvidence.length > 0 && allEvidence.every(item => item.status === 'fresh');
+    const ready = !planningViewLocked && noCompletionIssues && reviewIsFresh && allChecksFresh;
+    const complete = ready && (state.plan.verification ?? 'required') === 'required';
+    const status = state.status === 'blocked' ? 'blocked' : state.status === 'verified' && complete ? 'verified' : isStale ? 'stale' : state.status === 'verifying' ? 'verifying' : 'implementing';
+    const truncation = {
+      checks: { returned: evidence.length, total: allEvidence.length },
+      acceptance: { returned: plan.acceptance.length, total: state.plan.acceptance.length },
+      steps: { returned: plan.steps.length, total: state.plan.steps.length },
+      artifacts: { returned: plan.artifacts.length, total: state.plan.artifacts.length },
+      outputs: { returned: plan.outputs.length, total: state.plan.outputs?.length ?? 0 },
+      assumptions: { returned: plan.assumptions.length, total: state.plan.assumptions?.length ?? 0 },
+      scenarios: { returned: plan.scenarios.length, total: listLength(asRecord(state.plan.design).scenarios) },
+      risks: { returned: plan.risks.length, total: listLength(asRecord(state.plan.design).risks) },
+      workflowNodes: { returned: workflow.nodes.length, total: workflowView?.nodes?.length ?? 0 },
+      workflowEdges: { returned: workflow.edges.length, total: workflowView?.edges?.length ?? 0 },
+      architectureNodes: { returned: architecture.nodes.length, total: view.architecture?.nodes?.length ?? 0 },
+      architectureEdges: { returned: architecture.edges.length, total: view.architecture?.edges?.length ?? 0 },
+      architecturePorts: { returned: architecture.ports.length, total: view.architecture?.ports?.length ?? 0 },
+    };
+    const result = { status, freshness: isStale ? 'stale' : 'current', completion: ready ? 'ready' : 'incomplete', gate: gate.locked ? 'locked' : 'open', runId: state.runId, revision: state.revision, fingerprint: current, plan, workflow, architecture, evidence, truncation };
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 64 * 1024) return { status: 'invalid' } as const;
+    return result;
+  } catch {
+    return { status: 'invalid' } as const;
+  }
+}
+type ReviewModel = { providerID: string; id: string; variant?: string };
+
+function configuredReviewModel(value: unknown): ReviewModel | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || !('providerID' in value) || typeof value.providerID !== 'string' || !value.providerID.trim() || !('id' in value) || typeof value.id !== 'string' || !value.id.trim()) {
+    throw new Error('Invalid server reviewModel: providerID and id must be non-empty strings');
+  }
+  if ('variant' in value && value.variant !== undefined && (typeof value.variant !== 'string' || !value.variant.trim())) {
+    throw new Error('Invalid server reviewModel: variant must be a non-empty string when provided');
+  }
+  return { providerID: value.providerID.trim(), id: value.id.trim(), ...('variant' in value && typeof value.variant === 'string' ? { variant: value.variant.trim() } : {}) };
+}
+
+function taskStatus(session?: NativeSession, running = false) {
+  if (!session) return 'unavailable';
+  if (running) return 'running';
+  if (session.outcome === 'failed' || session.outcome === 'interrupted') return session.outcome;
+  // A successful model turn does not complete the durable logical delivery task.
+  return 'unknown';
+}
+
+/** Register real native workspace operations. Durable task records identify sessions which
+ * must be verified through the location-scoped native API; the TUI adds its full native list. */
+export async function registerWorkspaceRpc(ctx: Context, options: {
+  notify?: (summary: WorkspaceSnapshot) => void;
+  reviewModel?: ReviewModel;
+} = {}) {
+  const reviewModel = configuredReviewModel(options.reviewModel);
+  const root = resolve(ctx.location.project.canonical);
+  const locationDirectory = resolve(ctx.location.directory);
+  const projectID = ctx.location.project.id;
+  let disposed = false;
+  const events = new AbortController();
+  const running = new Set<string>();
+  const records = () => listTasks({ canonical: root, includeOperations: true }) as TaskState;
+  const owns = async (sessionID: string, signal?: AbortSignal) => {
+    signal?.throwIfAborted();
+    const session = await ctx.session.get({ sessionID }, { signal });
+    const taskState = records();
+    const task = taskState.tasks.find(record => record.sessionID === sessionID);
+    const directory = resolve(session.location.directory);
+    const operation = taskState.operations.find(record => record.sessionID === sessionID);
+    const ownedTask = task ?? (operation?.worktree ? operation as TaskRecord : undefined);
+    if (session.projectID !== projectID || directory !== root && directory !== locationDirectory && (!ownedTask || resolve(ownedTask.worktree) !== directory)) throw new Error('Session belongs to another workspace location');
+    return session;
+  };
+
+  const snapshot = async (requestedProjectID?: string, signal?: AbortSignal): Promise<WorkspaceSnapshot> => {
+    if (requestedProjectID && requestedProjectID !== projectID) throw new Error('Project is outside this OpenCode workspace location');
+    const taskState = records();
+    const ids = [...new Set([...taskState.tasks.map(record => record.sessionID), ...taskState.operations.map(record => record.sessionID)].filter((id): id is string => typeof id === 'string'))];
+    signal?.throwIfAborted();
+    const sessions = await Promise.all(ids.map(async id => {
+      try { return { id, session: await owns(id, signal), status: 'verified' as const }; } catch (error) {
+        if (signal?.aborted) throw error;
+        return { id, session: null, status: 'unavailable' as const };
+      }
+    }));
+    const byID = new Map(sessions.filter(item => item.session).map(item => [item.id, item.session!]));
+    const tasks: WorkspaceSnapshot['tasks'] = taskState.tasks.map(record => {
+      const session = byID.get(record.sessionID);
+      return {
+        id: record.id, projectID, title: record.task, status: taskStatus(session, running.has(record.sessionID)),
+        ...(!session || session.outcome === 'failed' || session.outcome === 'interrupted' ? { attention: true } : {}),
+        directory: record.worktree, ...(record.branch ? { branch: record.branch } : {}),
+      };
+    });
+    for (const op of taskState.operations) if (op.status !== 'complete' && op.status !== 'reconciled') {
+      tasks.push({ id: op.id, projectID, title: op.task, status: op.status, attention: op.status === 'recovery-required', ...(op.worktree ? { directory: op.worktree } : {}), ...(op.branch ? { branch: op.branch } : {}) });
+    }
+    return {
+      projects: [{ id: projectID, directory: root, name: basename(root) }], tasks,
+      sessions: sessions.flatMap(item => {
+        if (!item.session) return [{ id: item.id, title: 'Session unavailable', status: 'unavailable', directory: taskState.tasks.find(record => record.sessionID === item.id)?.worktree ?? locationDirectory }];
+        const session = item.session;
+        const task = taskState.tasks.find(record => record.sessionID === session.id);
+        return {
+          id: session.id, ...(task ? { taskID: task.id, projectID } : {}), title: session.title ?? 'Untitled session',
+          status: running.has(session.id) ? 'running' : session.outcome ?? 'unknown', updatedAt: new Date(session.time.updated).toISOString(), directory: session.location.directory,
+        };
+      }),
+    };
+  };
+
+  const registration = await ctx.rpc.register(Workspace, {
+    snapshot: async (value, call) => { const input = value as { projectID?: string }; return snapshot(input.projectID, call.signal); },
+    open: async (value, call) => {
+      const input = value as { sessionID: string };
+      const session = await owns(input.sessionID, call.signal);
+      call.signal.throwIfAborted();
+      await ctx.session.get({ sessionID: session.id }, { signal: call.signal });
+      return { opened: true, directory: session.location.directory };
+    },
+    createWorktree: async (value, call) => {
+      const input = value as { projectID: string; name: string };
+      if (input.projectID !== projectID) throw new Error('Project is outside this OpenCode workspace location');
+      call.signal.throwIfAborted();
+      const result = await ctx.worktree.create({ projectID, name: input.name }, { signal: call.signal });
+      return { directory: resolve(result.directory) };
+    },
+    createTask: async (value, call) => {
+      const input = value as { task: string; branch?: string };
+      call.signal.throwIfAborted();
+      const record = await createTask({ ctx, canonical: root, projectID, task: input.task, branch: input.branch, signal: call.signal });
+      await emitUpdated();
+      return { taskID: record.id, sessionID: record.sessionID, directory: record.worktree };
+    },
+    delivery: async (value, call) => {
+      const input = value as { sessionID: string };
+      const session = await owns(input.sessionID, call.signal);
+      const directory = resolve(session.location.directory);
+      if (session.projectID !== projectID) throw new Error('Session belongs to another project');
+      const task = records().tasks.find(record => record.sessionID === session.id);
+      const operation = records().operations.find(record => record.sessionID === session.id);
+      const expectedDirectory = task?.worktree ?? operation?.worktree ?? locationDirectory;
+      if (directory !== resolve(expectedDirectory)) throw new Error('Delivery report is not owned by this session');
+      return reportFor(directory, session.id);
+    },
+    review: async (value, call) => {
+      const input = value as { sessionID: string };
+      const session = await owns(input.sessionID, call.signal);
+      const report = reportFor(session.location.directory, session.id);
+      const receiptPath = resolve(session.location.directory, '.harness', 'reviews', `${createHash('sha256').update(`session:${session.id}`).digest('hex')}.json`);
+      if (!existsSync(receiptPath)) return { status: report.status === 'stale' || report.status === 'invalid' ? report.status : 'unreviewed' };
+      const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+      const current = localReviewSnapshot(session.location.directory);
+      const valid = receipt?.version === 1 && receipt.identity === `session:${session.id}` && Array.isArray(receipt.history);
+      if (!valid) return { status: 'invalid' };
+      const fresh = receipt.snapshot === current.snapshot && receipt.head === current.head && ['approved', 'changes-requested'].includes(receipt.status);
+      return { status: fresh ? receipt.status : 'stale', summary: fresh ? `${receipt.rounds} review round(s) · ${current.snapshot}` : 'Review source changed since this receipt' };
+    },
+    startReview: async (value, call) => {
+      const input = value as { sessionID: string };
+      const session = await owns(input.sessionID, call.signal);
+      try {
+        const result = await startReview({ ctx, cwd: session.location.directory, identity: `session:${session.id}`, model: reviewModel, signal: call.signal });
+        return { status: result.verdict === 'APPROVE' ? 'approved' : 'changes-requested', summary: `${result.findings.findings.length} findings · ${result.snapshot}`, sessionID: result.reviewerSessionID };
+      } catch (error) {
+        if (call.signal.aborted) throw error;
+        return call.error('reviewFailed', error instanceof Error ? error.message : String(error), { message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+
+  const emitUpdated = async () => {
+    if (!disposed) await registration.events.emit('updated', { revision: new Date().toISOString() });
+  };
+  const watcher = (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: events.signal })) {
+        if (disposed) return;
+        const detail = event as { type: string; location?: { directory: string }; data?: { sessionID?: string; status?: { type?: string } } };
+        const sessionID = detail.data?.sessionID;
+        let sessionDirectory: string | undefined;
+        if (sessionID) {
+          try {
+            const session = await owns(sessionID);
+            sessionDirectory = resolve(session.location.directory);
+          } catch {
+            const taskState = records();
+            const task = taskState.tasks.find(record => record.sessionID === sessionID);
+            const operation = taskState.operations.find(record => record.sessionID === sessionID);
+            const recordedDirectory = task?.worktree ?? operation?.worktree;
+            const eventDirectory = detail.location?.directory && resolve(detail.location.directory);
+            if (recordedDirectory && detail.type === 'session.deleted') sessionDirectory = resolve(recordedDirectory);
+            else if (eventDirectory && [root, locationDirectory, ...taskState.tasks.map(record => resolve(record.worktree)), ...taskState.operations.map(record => record.worktree ? resolve(record.worktree) : undefined).filter((directory): directory is string => Boolean(directory))].includes(eventDirectory)) sessionDirectory = eventDirectory;
+            else continue;
+          }
+        }
+        const taskDirectories = [...records().tasks.map(task => resolve(task.worktree)), ...records().operations.map(operation => operation.worktree && resolve(operation.worktree)).filter((directory): directory is string => Boolean(directory))];
+        const relevantDirectories = new Set([root, locationDirectory, ...taskDirectories]);
+        if (sessionDirectory && !relevantDirectories.has(sessionDirectory)) continue;
+        if (!sessionID && detail.location?.directory && !relevantDirectories.has(resolve(detail.location.directory))) continue;
+        if (!sessionID && !detail.location?.directory) continue;
+        if (detail.type.startsWith('session.execution.') && sessionID) {
+          if (detail.type === 'session.execution.started') running.add(sessionID);
+          else if (['session.execution.succeeded', 'session.execution.failed', 'session.execution.interrupted'].includes(detail.type)) running.delete(sessionID);
+        }
+        if (detail.type === 'session.status' && sessionID && detail.data?.status?.type) {
+          if (detail.data.status.type === 'busy' || detail.data.status.type === 'retry') running.add(sessionID);
+          else running.delete(sessionID);
+        }
+        if (['session.updated', 'session.created', 'session.deleted', 'session.status', 'session.execution.started', 'session.execution.succeeded', 'session.execution.failed', 'session.execution.interrupted', 'worktree.updated'].includes(detail.type)) {
+          try {
+            const value = await snapshot();
+            options.notify?.(value);
+          } catch { /* Updates are invalidations; reads fail closed. */ }
+          try { await emitUpdated(); } catch { /* A disconnected subscriber must not kill the native event stream. */ }
+        }
+      }
+    } catch { /* Stream ends with host teardown; no polling or retry loop. */ }
+  })();
+
+  return async () => {
+    disposed = true;
+    events.abort();
+    await registration.dispose();
+    await watcher;
+  };
+}

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

@@ -0,0 +1,31 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+const errors = {
+  wrong_workspace: {
+    type: 'object', properties: { sessionID: { type: 'string' } },
+    required: ['sessionID'], additionalProperties: false,
+  },
+} as const;
+
+export const SessionControls = Rpc.define({
+  id: 'carthagent.session',
+  methods: {
+    framing: {
+      input: {
+        type: 'object', properties: { sessionID: { type: 'string', minLength: 1 }, enabled: { type: 'boolean' } },
+        required: ['sessionID'], additionalProperties: false,
+      },
+      output: { type: 'object', properties: { enabled: { type: 'boolean' } }, required: ['enabled'], additionalProperties: false },
+      errors,
+    },
+    compact: {
+      input: {
+        type: 'object', properties: { sessionID: { type: 'string', minLength: 1 }, notes: { type: 'string', maxLength: 16000 } },
+        required: ['sessionID'], additionalProperties: false,
+      },
+      output: { type: 'object', properties: { admitted: { type: 'boolean' } }, required: ['admitted'], additionalProperties: false },
+      errors,
+    },
+  },
+  events: {},
+});

package/plugins/carthagent/src/testing.ts

@@ -0,0 +1,85 @@
+import { registerSessionControls } from './server/session-controls';
+import { registerNativeDelivery } from './server/native-delivery';
+import { Carthagent } from './rpc';
+import type { Context } from '@opencode/plugin/promise/plugin';
+import type { ShellHooks } from '@opencode/plugin/promise/shell';
+
+const TestDiagnostics = {
+  id: 'carthagent-test',
+  methods: {
+    state: {
+      input: { type: 'object', properties: { sessionID: { type: 'string', minLength: 1 } }, required: ['sessionID'], additionalProperties: false },
+      output: { type: 'object', properties: {
+        budget: { type: ['object', 'null'], additionalProperties: true },
+        delivery: { type: ['object', 'null'], additionalProperties: true },
+        invocations: { type: 'array', items: { type: 'object', additionalProperties: true } },
+      }, required: ['budget', 'delivery', 'invocations'], additionalProperties: false },
+    },
+  },
+  events: {},
+} as const;
+
+/** Full host registration for the isolated native integration harness. */
+export async function setupNativeTestPlugin(context: Parameters<typeof registerSessionControls>[0]) {
+  const cleanups: Array<() => Promise<void>> = [];
+  const invocations: Array<{ hook: string; tool?: string; command?: string }> = [];
+  const monitored = {
+    ...context,
+    tool: {
+      ...context.tool,
+      hook: async (name: 'execute.before' | 'execute.after', callback: (event: { tool: string; id: string; sessionID: string }) => unknown) => context.tool.hook(name, async (event) => {
+        if (name === 'execute.before' || name === 'execute.after') invocations.push({ hook: name, tool: event.tool });
+        await callback(event);
+      }),
+    },
+    shell: {
+      ...context.shell,
+      hook: async (name: keyof ShellHooks, callback: (event: ShellHooks[keyof ShellHooks]) => unknown) => context.shell.hook(name, async (event) => {
+        if (name === 'create.before') invocations.push({ hook: `shell.${name}`, command: event.command });
+        await callback(event);
+      }),
+    },
+  } as unknown as Context;
+  try {
+    cleanups.push(await registerSessionControls(monitored));
+    cleanups.push(await registerNativeDelivery(monitored));
+    const registration = await context.rpc.register(Carthagent, {
+      health: async () => ({ protocol: 1, hostVersion: context.app.version, directory: context.location.directory }),
+      echo: async input => ({ text: (input as { text: string }).text }),
+      authStart: async () => { throw new Error('Device authorization is not available in the isolated delivery test plugin.'); },
+      authCancel: async () => ({ cancelled: false }),
+    });
+    cleanups.push(async () => registration.dispose());
+    const diagnostics = await context.rpc.register(TestDiagnostics, {
+      state: async (input) => {
+        const { sessionID } = input as { sessionID: string };
+        const stored = await context.storage.get(`session/${sessionID}`);
+        const state = stored && typeof stored === 'object' && !Array.isArray(stored) ? stored as Record<string, unknown> : undefined;
+        return {
+          budget: isRecord(state?.budget) ? { tools: state.budget.tools, limits: state.budget.limits, stopped: state.budget.stopped } : null,
+          delivery: isRecord(state?.state) ? {
+            workflowMode: state.state.workflowMode,
+            status: state.state.status,
+            planning: isRecord(state.state.planning) ? JSON.parse(JSON.stringify({
+              validation: state.state.planning.validation,
+              capture: isRecord(state.state.planning.capture) ? { id: state.state.planning.capture.id } : null,
+              review: state.state.planning.review,
+              approval: state.state.planning.approval,
+              started: state.state.planning.started,
+            })) : null,
+          } : null,
+          invocations,
+        };
+      },
+    });
+    cleanups.push(async () => diagnostics.dispose());
+    return async () => { for (const cleanup of cleanups.reverse()) await cleanup(); };
+  } catch (error) {
+    await Promise.allSettled(cleanups.reverse().map(cleanup => cleanup()));
+    throw error;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,133 @@
+import { Rpc } from '@opencode/plugin/rpc';
+
+const string = { type: 'string', minLength: 1 } as const;
+const sessionInput = {
+  type: 'object', properties: { sessionID: string }, required: ['sessionID'], additionalProperties: false,
+} as const;
+const project = {
+  type: 'object', properties: { id: string, directory: string, name: string },
+  required: ['id', 'directory'], additionalProperties: false,
+} as const;
+const task = {
+  type: 'object', properties: {
+    id: string, projectID: string, title: string, status: string,
+    attention: { type: 'boolean' }, directory: string, branch: string,
+  }, required: ['id', 'projectID', 'title', 'status'], additionalProperties: false,
+} as const;
+const session = {
+  type: 'object', properties: {
+    id: string, taskID: string, projectID: string, title: { type: 'string' }, status: string,
+    updatedAt: string, directory: string,
+  }, required: ['id', 'title', 'status', 'directory'], additionalProperties: false,
+} as const;
+const evidenceItem = {
+  type: 'object', properties: {
+    id: string, status: { type: 'string', enum: ['pending', 'failed', 'fresh', 'stale'] },
+    executedRevision: { type: 'integer' }, code: { type: 'integer' }, filename: string,
+  }, required: ['id', 'status'], additionalProperties: false,
+} as const;
+const deliveryPlan = {
+  type: 'object', properties: {
+    goal: { type: 'string' }, verification: { type: 'string' },
+    acceptance: { type: 'array', items: { type: 'object', properties: { requirement: { type: 'string' }, checks: { type: 'array', items: string } }, required: ['requirement', 'checks'], additionalProperties: false } },
+    artifacts: { type: 'array', items: { type: 'string' } }, outputs: { type: 'array', items: { type: 'string' } }, assumptions: { type: 'array', items: { type: 'string' } },
+    checks: { type: 'array', items: { type: 'object', properties: { id: string, kind: { type: 'string' }, argv: { type: 'array', items: { type: 'string' } }, timeoutSeconds: { type: 'integer' } }, required: ['id', 'kind', 'argv', 'timeoutSeconds'], additionalProperties: false } },
+    steps: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, title: { type: 'string' }, status: { type: 'string' }, dependsOn: { type: 'array', items: { type: 'string' } }, checks: { type: 'array', items: { type: 'string' } } }, required: ['id', 'title', 'status', 'dependsOn', 'checks'], additionalProperties: false } },
+    scenarios: { type: 'array', items: { type: 'object', properties: { id: string, requirement: { type: 'string' }, kind: { type: 'string' }, path: { type: 'array', items: { type: 'string' } }, checks: { type: 'array', items: { type: 'string' } }, input: { type: 'string' }, expected: { type: 'string' }, assertion: { type: 'string' } }, required: ['id', 'requirement', 'kind', 'path', 'checks', 'input', 'expected', 'assertion'], additionalProperties: false } },
+    risks: { type: 'array', items: { type: 'object', properties: { id: string, description: { type: 'string' }, status: { type: 'string' }, blocking: { type: 'boolean' }, evidence: { type: 'string' } }, required: ['id', 'description', 'status', 'blocking', 'evidence'], additionalProperties: false } },
+  }, required: ['goal', 'verification', 'acceptance', 'steps', 'artifacts', 'outputs', 'assumptions', 'checks', 'scenarios', 'risks'], additionalProperties: false,
+} as const;
+const graphNodes = { type: 'array', items: { type: 'object', properties: { id: string, title: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, layer: { type: 'string' }, excludes: { type: 'array', items: { type: 'string' } }, requirements: { type: 'array', items: { type: 'string' } } }, required: ['id', 'title'], additionalProperties: false } } as const;
+const graphEdges = { type: 'array', items: { type: 'object', properties: { from: { type: 'string' }, to: { type: 'string' }, kind: { type: 'string' }, label: { type: 'string' } }, required: ['from', 'to', 'kind'], additionalProperties: false } } as const;
+const workflowGraph = {
+  type: 'object', properties: {
+    authored: { type: 'boolean' }, semantics: { type: 'string' },
+    nodes: { type: 'array', items: { type: 'object', properties: {
+      id: string, title: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, step: { type: 'string' },
+      requirements: { type: 'array', items: { type: 'string' } }, components: { type: 'array', items: { type: 'string' } }, checks: { type: 'array', items: { type: 'string' } },
+      inputs: { type: 'array', items: { type: 'string' } }, artifacts: { type: 'array', items: { type: 'string' } }, effects: { type: 'array', items: { type: 'string' } }, condition: { type: 'string' },
+    }, required: ['id', 'title', 'type', 'status', 'requirements', 'components', 'checks', 'inputs', 'artifacts', 'effects'], additionalProperties: false } },
+    edges: { type: 'array', items: { type: 'object', properties: { from: { type: 'string' }, to: { type: 'string' }, kind: { type: 'string' }, label: { type: 'string' }, when: { type: 'string' }, stop: { type: 'string' }, maxAttempts: { type: 'integer' } }, required: ['from', 'to', 'kind'], additionalProperties: false } },
+  }, required: ['authored', 'semantics', 'nodes', 'edges'], additionalProperties: false,
+} as const;
+const architectureGraph = {
+  type: 'object', properties: {
+    nodes: graphNodes, edges: graphEdges,
+    ports: { type: 'array', items: { type: 'object', properties: { id: string, owner: string, adapter: string, compositionRoot: string, input: { type: 'string' }, output: { type: 'string' }, errors: { type: 'string' }, injection: { type: 'string' }, testDouble: { type: 'string' }, integrationAssertion: { type: 'string' } }, required: ['id', 'owner', 'adapter', 'compositionRoot', 'input', 'output', 'errors', 'injection', 'testDouble', 'integrationAssertion'], additionalProperties: false } },
+  }, required: ['nodes', 'edges', 'ports'], additionalProperties: false,
+} as const;
+const deliveryTruncation = {
+  type: 'object', properties: Object.fromEntries(['checks', 'acceptance', 'steps', 'artifacts', 'outputs', 'assumptions', 'scenarios', 'risks', 'workflowNodes', 'workflowEdges', 'architectureNodes', 'architectureEdges', 'architecturePorts'].map(key => [key, { type: 'object', properties: { returned: { type: 'integer' }, total: { type: 'integer' } }, required: ['returned', 'total'], additionalProperties: false }])), required: ['checks', 'acceptance', 'steps', 'artifacts', 'outputs', 'assumptions', 'scenarios', 'risks', 'workflowNodes', 'workflowEdges', 'architectureNodes', 'architectureEdges', 'architecturePorts'], additionalProperties: false,
+} as const;
+const deliveryFullProperties = {
+  status: { type: 'string', enum: ['active', 'implementing', 'verifying', 'verified', 'blocked', 'stale'] },
+  freshness: { type: 'string', enum: ['current', 'stale'] },
+  completion: { type: 'string', enum: ['ready', 'incomplete'] },
+  gate: { type: 'string', enum: ['locked', 'open'] },
+  runId: string,
+  revision: { type: 'integer' },
+  fingerprint: { type: 'string', minLength: 64, maxLength: 64 },
+  plan: deliveryPlan,
+  workflow: workflowGraph,
+  architecture: architectureGraph,
+  evidence: { type: 'array', items: evidenceItem },
+  truncation: deliveryTruncation,
+} as const;
+const deliveryOutput = {
+  oneOf: [
+    { type: 'object', properties: deliveryFullProperties, required: Object.keys(deliveryFullProperties), additionalProperties: false },
+    { type: 'object', properties: { status: { type: 'string', enum: ['unavailable', 'invalid'] } }, required: ['status'], additionalProperties: false },
+  ],
+} as const;
+
+/** Shared server/TUI contract. Callers supply the intended native location on every call. */
+export const Workspace = Rpc.define({
+  id: 'carthagent.workspace',
+  methods: {
+    snapshot: {
+      input: { type: 'object', properties: { projectID: string }, additionalProperties: false },
+      output: {
+        type: 'object', properties: {
+          projects: { type: 'array', items: project }, tasks: { type: 'array', items: task },
+          sessions: { type: 'array', items: session },
+        }, required: ['projects', 'tasks', 'sessions'], additionalProperties: false,
+      },
+    },
+    open: {
+      input: sessionInput,
+      output: { type: 'object', properties: { opened: { type: 'boolean' }, directory: string }, required: ['opened', 'directory'], additionalProperties: false },
+    },
+    createWorktree: {
+      input: { type: 'object', properties: { projectID: string, name: string }, required: ['projectID', 'name'], additionalProperties: false },
+      output: { type: 'object', properties: { directory: string }, required: ['directory'], additionalProperties: false },
+    },
+    createTask: {
+      input: { type: 'object', properties: { task: string, branch: string }, required: ['task'], additionalProperties: false },
+      output: { type: 'object', properties: { taskID: string, sessionID: string, directory: string }, required: ['taskID', 'sessionID', 'directory'], additionalProperties: false },
+    },
+    delivery: {
+      input: sessionInput,
+      output: deliveryOutput,
+    },
+    review: {
+      input: sessionInput,
+      output: { type: 'object', properties: { status: string, summary: { type: 'string' } }, required: ['status'], additionalProperties: false },
+    },
+    startReview: {
+      input: sessionInput,
+      output: { type: 'object', properties: { status: string, summary: { type: 'string' }, sessionID: string }, required: ['status', 'summary'], additionalProperties: false },
+      errors: {
+        reviewFailed: { data: { type: 'object', properties: { message: string }, required: ['message'], additionalProperties: false } },
+      },
+    },
+  },
+  events: {
+    updated: { schema: { type: 'object', properties: { revision: string }, required: ['revision'], additionalProperties: false } },
+  },
+});
+
+export interface WorkspaceSnapshot {
+  projects: Array<{ id: string; directory: string; name?: string }>;
+  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 }>;
+}

package/plugins/carthagent/test-plugin/index.ts

@@ -0,0 +1,4 @@
+import { Plugin } from '@opencode/plugin';
+import { setupNativeTestPlugin } from '../src/testing';
+
+export default Plugin.define({ id: 'carthagent', setup: setupNativeTestPlugin });

package/plugins/carthagent/test-plugin/package.json

@@ -0,0 +1 @@
+{"name":"@carthagent/native-integration-test-plugin","version":"1.0.0","type":"module","private":true}

package/plugins/carthagent/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "@opentui/solid",
+    "strict": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true
+  },
+  "include": ["*.ts", "src/**/*.ts", "src/**/*.tsx"]
+}