carthagent 1.0.7 → 1.1.0-preview.13

package/plugins/carthagent/src/server/framing.mjs

@@ -0,0 +1,80 @@
+/**
+ * Behind-the-scenes phased-delivery framing (the carthagent default flow).
+ *
+ * Every typed task is a phased delivery run: the raw text is what the user
+ * sees echoed in the feed, while the engine receives the expanded delivery template
+ * body. Resolving the template here (rather than forwarding "/guide <task>"
+ * to the engine) keeps the behavior identical in --isolate and headless -p modes,
+ * and keeps the machinery invisible in the feed.
+ *
+ * This is the default flow for carthagent — the whole product is built around it —
+ * so the input pill stays empty and the hint rotates through generic
+ * builder one-liners.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '../../../..');
+const TEMPLATE_PATH = join(ROOT, 'prompts', 'delivery.md');
+
+let cached = null;
+
+export const FRAME_HINTS = ['Message carthagent…'];
+
+export function frameHint() {
+  return FRAME_HINTS[0];
+}
+
+function readTemplate(path) {
+  let body = '';
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const fm = raw.match(/^---\n[\s\S]*?\n---\n?/);
+    body = (fm ? raw.slice(fm[0].length) : raw).trim();
+  } catch { body = ''; }
+  return body;
+}
+
+/** Body of prompts/delivery.md with frontmatter stripped. '' when unreadable. */
+export function framingTemplate(path = TEMPLATE_PATH) {
+  if (path === TEMPLATE_PATH) {
+    if (cached == null) cached = readTemplate(TEMPLATE_PATH);
+    return cached;
+  }
+  return readTemplate(path);
+}
+
+/** Expand the delivery template for a task. Falls back to the bare task text. */
+export function framePrompt(task, template = framingTemplate()) {
+  const t = String(task).trim();
+  if (!template) return t;
+  return template.includes('$@') ? template.replaceAll('$@', t) : `${template}\n\n${t}`;
+}
+
+/** Recover the original task text from a framed prompt, else null. */
+export function unframe(text) {
+  // Match the current template suffix first: the task itself may contain
+  // blank lines (or even phase headings). Keep the legacy format fallback.
+  const value = String(text);
+  const template = framingTemplate();
+  const parts = template.split('$@');
+  if (parts.length === 2 && value.startsWith(parts[0]) && value.endsWith(parts[1])) {
+    return value.slice(parts[0].length, parts[1] ? -parts[1].length : undefined).trim();
+  }
+  const m = value.match(/^Deliver this task in phases(?: with executable evidence)?:\s*([\s\S]*?)\n\n/);
+  return m ? m[1].trim() : null;
+}
+
+/** True when a submitted prompt should get the delivery framing. */
+export function shouldFrame(text, { enabled = true, delivery = true } = {}) {
+  if (!enabled || !delivery) return false;
+  const v = String(text).trim();
+  if (!v) return false;
+  if (v.startsWith('/') || v.startsWith('!')) return false;
+  // Questions/read-only asks are not delivery runs.
+  if (v.endsWith('?') && v.length < 300) return false;
+  if (/^(what|why|how|explain|show|list|describe|review|where|is|are|does|do|can)\b/i.test(v) && v.length < 300 && !/\b(build|create|implement|write|add|fix|make|generate)\b/i.test(v)) return false;
+  return existsSync(TEMPLATE_PATH);
+}

package/plugins/carthagent/src/server/policy.ts

@@ -8,7 +8,7 @@ type DeliveryState = Parameters<typeof startImplementation>[0]
 export const READ_ONLY_TOOLS = new Set(["read", "ls", "find", "grep", "code_nav", "delivery_probe"])
 
 export function requiresPlanApproval(tool: string) {
-  return needsImplementation(tool)
+  return !["glob", "skill", "question"].includes(tool) && needsImplementation(tool.replace(/^carthagent_/, ""))
 }
 
 export function enforceToolPolicy(tool: string, state: DeliveryState, cwd: string) {

package/plugins/carthagent/src/server/providers.ts

@@ -25,9 +25,10 @@ import {
 import { catalogModels } from '../../../../lib/providers/model-catalog.mjs';
 import { shipAgentDir } from '../../../../lib/ship-auth.mjs';
 import { createHash } from 'node:crypto';
-import { legacyOAuthForOpenCode, nativeCredentialFile, refreshNativeCredential, refreshSingleFlight } from '../../../../lib/opencode/credentials.mjs';
+import { legacyOAuthForOpenCode, nativeCredentialFile, nativeCredentialDatabaseFile, readNativeOAuthCredential, refreshNativeCredential, refreshSingleFlight } from '../../../../lib/opencode/credentials.mjs';
 import { createDeviceAuthController } from './device-auth.ts';
 import { createSessionIdentity, isManagedShipCredential, shipTelemetryHeaders } from './telemetry.ts';
+import { nativeLoginProvider } from '../../../../lib/opencode/provider-policy.mjs';
 
 const OAUTH_METHOD = 'carthagent-device';
 const SHIP_INTEGRATION_ID = EXPERIENTIAL_PROVIDER_ID;
@@ -97,14 +98,14 @@ function modelInfo(providerID: string, profile: CatalogModel, defaultBaseURL: st
 
 function mapCompatibility(compat: Record<string, unknown>): NonNullable<Model.Info['compatibility']> {
   const keys = [
-    'reasoningField', 'requireReasoning', 'maxTokensField', 'requireFinishReason',
+    'reasoningField', 'requireReasoning', 'reasoningPlaceholder', 'maxTokensField', 'requireFinishReason',
     'requireAssistantAfterTool', 'supportsPromptCacheKey', 'cacheFormat',
     'supportsThinkingBlockBinding', 'supportsEffortUpdates',
   ] as const;
   return Object.fromEntries(keys.flatMap(key => key in compat ? [[key, compat[key]]] : [])) as NonNullable<Model.Info['compatibility']>;
 }
 
-function oauthMethod({ env, fetchImpl, sleep, now, openBrowserImpl, agentDir, startDeviceFlow, rereadCredential, credentialFile }: {
+function oauthMethod({ env, fetchImpl, sleep, now, openBrowserImpl, agentDir, startDeviceFlow, credentialFile, coordinationFile }: {
   env: NodeJS.ProcessEnv;
   fetchImpl: typeof fetch;
   sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -112,15 +113,21 @@ function oauthMethod({ env, fetchImpl, sleep, now, openBrowserImpl, agentDir, st
   openBrowserImpl: typeof openBrowser;
   agentDir: string;
   startDeviceFlow: () => Promise<{ authorization: { userCode: string; verificationUri: string; verificationUriComplete?: string; expiresIn: number; interval: number; deviceCode: string }; callback: Promise<Credential.OAuth> }>;
-  rereadCredential: () => Promise<Credential.OAuth | undefined>;
   credentialFile: string;
+  coordinationFile: string;
 }) {
   const client = new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl, sleep: ms => sleep(ms) });
   return {
     integrationID: IntegrationSchema.ID.make(SHIP_INTEGRATION_ID),
-    method: { id: OAUTH_METHOD, type: 'oauth' as const, label: 'Sign in with Carthagent Ship' },
-    authorize: async (_answer: Form.Answer) => {
-      const legacy = await legacyOAuthForOpenCode({ agentDir });
+    method: {
+      id: OAUTH_METHOD, type: 'oauth' as const, label: 'Sign in with Carthagent Ship',
+      form: [{ type: 'boolean' as const, key: 'importLegacy', title: 'Import a legacy Ship credential instead of signing in?',
+        description: 'Leave disabled for fresh browser approval and updated account permissions.', default: false }] satisfies Form.Fields,
+    },
+    authorize: async (answer: Form.Answer) => {
+      // The legacy file intentionally survives migration. Never let its presence
+      // short-circuit an explicit sign-in or recovery from revoked/old scopes.
+      const legacy = answer.importLegacy === true ? await legacyOAuthForOpenCode({ agentDir }) : undefined;
       if (legacy) {
         return {
           mode: 'auto' as const,
@@ -146,15 +153,21 @@ function oauthMethod({ env, fetchImpl, sleep, now, openBrowserImpl, agentDir, st
       };
     },
     refresh: (credential: Credential.OAuth) => refreshSingleFlight(
-      `${credential.methodID}:${credential.refresh}`,
-      () => refreshNativeCredential({
-        credential,
-        credentialFile,
-        reread: rereadCredential,
-        refresh: async (current: Credential.OAuth) => ({ type: 'oauth' as const, methodID: IntegrationSchema.MethodID.make(OAUTH_METHOD),
-          ...oauthCredentials(await client.refresh({ refreshToken: current.refresh }), now()),
-          ...(current.metadata ? { metadata: current.metadata } : {}) }),
-      }),
+      `${coordinationFile}:${credential.methodID}:${credential.refresh}`,
+      async () => {
+        const credentialID = await readNativeOAuthCredential({ credentialFile,
+          integrationID: SHIP_INTEGRATION_ID, methodID: credential.methodID, refreshToken: credential.refresh });
+        return refreshNativeCredential({
+          credential,
+          credentialFile: coordinationFile,
+          credentialID,
+          reread: () => readNativeOAuthCredential({ credentialFile, credentialID,
+            integrationID: SHIP_INTEGRATION_ID, methodID: credential.methodID }),
+          refresh: async (current: Credential.OAuth) => ({ type: 'oauth' as const, methodID: IntegrationSchema.MethodID.make(OAUTH_METHOD),
+            ...oauthCredentials(await client.refresh({ refreshToken: current.refresh, signal: AbortSignal.timeout(10_000) }), now()),
+            ...(current.metadata ? { metadata: current.metadata } : {}) }),
+        });
+      },
     ),
     label: () => 'Carthagent Ship',
   };
@@ -164,6 +177,7 @@ function integrationDefinitions(editor: Parameters<Context['integration']['trans
   editor.method.update(oauthMethod(options));
   editor.method.update({ integrationID: IntegrationSchema.ID.make(SHIP_INTEGRATION_ID), method: { type: 'key', label: 'Use an Experiential API key' } });
   editor.method.update({ integrationID: IntegrationSchema.ID.make(SHIP_INTEGRATION_ID), method: { type: 'env', names: [EXPERIENTIAL_API_KEY_ENV] } });
+  editor.update(SHIP_INTEGRATION_ID, integration => { integration.name = EXPERIENTIAL_PROVIDER_NAME; });
 }
 
 function asModelInfo(providerID: string, model: { id: string }, baseURL: string) {
@@ -199,6 +213,7 @@ interface ProviderRegistrationOptions {
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
   agentDir?: string;
   credentialFile?: string;
+  vaultFile?: string;
   openBrowser?: typeof openBrowser;
   telemetryIdentity?: ReturnType<typeof createSessionIdentity>;
   sessionIdentity?: (event: SessionModelRequest) => string;
@@ -215,12 +230,10 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
   const agentDir = options.agentDir ?? shipAgentDir(env);
   const openBrowserImpl = options.openBrowser ?? openBrowser;
   const deviceAuth = options.deviceAuth ?? createDeviceAuthController({ env, fetchImpl, agentDir, now, sleep });
-  const rereadCredential = async (): Promise<Credential.OAuth | undefined> => {
-    const active = await ctx.integration.connection.active(SHIP_INTEGRATION_ID);
-    if (!active) return undefined;
-    const value = await ctx.integration.connection.resolve(active);
-    return value?.type === 'oauth' && value.methodID === OAUTH_METHOD ? value : undefined;
-  };
+  // credentialFile historically selects the coordination namespace. Retain
+  // the fixture shorthand (one explicit path for both) unless vaultFile is set.
+  const coordinationFile = options.credentialFile ?? nativeCredentialFile(env);
+  const credentialFile = options.vaultFile ?? options.credentialFile ?? nativeCredentialDatabaseFile(env, ctx.app.channel);
   const requestIdentity = options.sessionIdentity;
   const identity = options.telemetryIdentity ?? createSessionIdentity();
   const requestSecret = options.requestSecret ?? `${ctx.location?.project?.id || ctx.location?.directory || 'ctg'}:request-v1`;
@@ -236,23 +249,36 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
     return failures;
   };
   try {
+  const excludedIntegrations = new Set<string>();
   const integration = await ctx.integration.transform(editor => {
     integrationDefinitions(editor, {
     env, fetchImpl, sleep, now, openBrowserImpl, agentDir, startDeviceFlow: deviceAuth.start,
-    rereadCredential,
-    credentialFile: options.credentialFile ?? nativeCredentialFile(env),
+    credentialFile,
+    coordinationFile,
     });
+    for (const integration of editor.list()) {
+      const supported = nativeLoginProvider(integration.id);
+      if (supported) editor.update(integration.id, item => { item.name = supported.name; });
+      else {
+        excludedIntegrations.add(integration.id);
+        editor.remove(integration.id);
+      }
+    }
   });
   registrations.push(integration);
 
   const baseURL = experientialBaseUrl(env);
-  const shipModels: Model.Info[] = [];
+  let shipModels: Model.Info[] = [];
+  let shipConnection: ConnectionInfo | undefined;
   const subscriptions: Record<string, Model.Info[]> = { [ANTHROPIC_PROVIDER_ID]: [], [OPENAI_CODEX_PROVIDER_ID]: [] };
   const subscriptionConnections: Partial<Record<string, ConnectionInfo>> = {};
   const providerRegistration = await ctx.provider.transform(editor => {
+    for (const { provider } of editor.list()) {
+      if (provider.id.startsWith('opencode') || excludedIntegrations.has(provider.integrationID ?? provider.id)) editor.remove(provider.id);
+    }
     editor.add({ info: providerInfo(EXPERIENTIAL_PROVIDER_ID, EXPERIENTIAL_PROVIDER_NAME,
       '@opencode/ai/providers/openai-compatible', SHIP_INTEGRATION_ID,
-      { baseURL, apiKey: `$${EXPERIENTIAL_API_KEY_ENV}` }), models: shipModels });
+      { baseURL, apiKey: `$${EXPERIENTIAL_API_KEY_ENV}` }), models: shipModels, sourceConnection: shipConnection });
     // Subscription IDs already exist in the native catalog. Overlay only the
     // definitions and retain catalog cost/capability metadata.
     for (const [providerID, baseURL] of [
@@ -330,8 +356,10 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
   const refresh = async (signal?: AbortSignal): Promise<void> => {
     const inventory = await loadShipModels({ ctx, fetchImpl, env, baseURL, signal });
     if (inventory?.models) {
-      shipModels.splice(0, shipModels.length, ...inventory.models.map(model => asModelInfo(EXPERIENTIAL_PROVIDER_ID, model,
-        inventory.managed ? cloudGatewayUrl(env) : baseURL)));
+      shipConnection = inventory.connection;
+      // The host indexes immutable model arrays by identity.
+      shipModels = inventory.models.map(model => asModelInfo(EXPERIENTIAL_PROVIDER_ID, model,
+        inventory.managed ? cloudGatewayUrl(env) : baseURL));
       await ctx.provider.reload();
     }
     for (const providerID of [ANTHROPIC_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID]) {
@@ -340,7 +368,7 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
       if (!active) {
         if (subscriptionConnections[providerID]) {
           delete subscriptionConnections[providerID];
-          subscriptions[providerID].splice(0, subscriptions[providerID].length);
+          subscriptions[providerID] = [];
           await ctx.provider.reload();
         }
         continue;
@@ -357,7 +385,7 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
       const accountMetadata = credential && 'metadata' in credential ? credential.metadata as Record<string, unknown> | undefined : undefined;
       const accountKey = createHash('sha256').update(String(('id' in active ? active.id : '') || accountMetadata?.accountId || (credential?.type === 'oauth' ? credential.access : credential?.type === 'key' ? credential.key : '') || '')).digest('hex');
       if (prior?.account !== accountKey) {
-        subscriptions[providerID].splice(0, subscriptions[providerID].length);
+        subscriptions[providerID] = [];
       }
       const known = new Map([
         ...catalogModels(providerID).map((model: CatalogModel) => [model.id, model] as const),
@@ -369,7 +397,7 @@ export async function registerProviders(ctx: Context, options: ProviderRegistrat
           ? anthropicModelDefinition(model, base) : codexModelDefinition(model, base),
         providerID === ANTHROPIC_PROVIDER_ID ? 'https://api.anthropic.com' : 'https://chatgpt.com/backend-api');
       });
-      subscriptions[providerID].splice(0, subscriptions[providerID].length, ...converted);
+      subscriptions[providerID] = converted;
       subscriptionConnections[providerID] = active;
       await ctx.storage.set(cacheKey, { account: accountKey, models: discovered, checkedAt: now() });
       await ctx.provider.reload();

package/plugins/carthagent/src/server/session-controls.ts

@@ -1,6 +1,7 @@
 import type { Context } from '@opencode/plugin/promise/plugin';
-import { framePrompt, shouldFrame, unframe } from '../../../../lib/tui/framing.mjs';
+import { framePrompt, shouldFrame, unframe } from './framing.mjs';
 import { SessionControls } from '../session-rpc';
+import { isShipAgent } from './ship-agents';
 import { effectiveSessionOptions } from '../../../../lib/opencode/session-options.mjs';
 
 /** Admission framing is session-scoped; raw bypasses framing, never delivery policy. */
@@ -25,6 +26,7 @@ export async function registerSessionControls(ctx: Context) {
     const prompt = await ctx.session.hook('prompt', async (event) => {
       const session = await ctx.session.get({ sessionID: event.sessionID });
       const options = effectiveSessionOptions(session, ctx.options);
+      if (!isShipAgent(session.agent)) return;
       const saved = await settings(event.sessionID);
       if (event.metadata?.['ctg.raw'] === true || event.metadata?.['ctg.framed'] === true) return;
       if (!shouldFrame(event.prompt.text, {

package/plugins/carthagent/src/server/ship-agents.ts

@@ -0,0 +1,77 @@
+import type { Context } from "@opencode/plugin/promise/plugin"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const SHIP_AGENT_ID = "ship"
+export const LITE_AGENT_ID = "lite"
+
+const SKILLS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../skills")
+
+/**
+ * The delivery harness runs only for Ship. A missing agent ID means the host could not
+ * identify the mode, so enforcement stays on rather than silently disappearing.
+ */
+export function isShipAgent(agent: string | undefined | null) {
+  return agent === undefined || agent === null || agent === "" || agent === SHIP_AGENT_ID
+}
+
+type AgentEditor = Parameters<Parameters<Context["agent"]["transform"]>[0]>[0]
+type SkillEditor = Parameters<Parameters<Context["skill"]["transform"]>[0]>[0]
+
+/**
+ * Ship deliberately sets no `system` override: the host keeps its native base prompt and the
+ * delivery plugin injects the workflow per request, as the legacy extension appended it.
+ */
+export async function registerShipAgents(ctx: Pick<Context, "agent">) {
+  const registration = await ctx.agent.transform((editor: AgentEditor) => {
+    editor.update(SHIP_AGENT_ID, item => {
+      item.name = "Ship" as unknown as typeof item.name
+      item.description = "Carthagent delivery workflow: acceptance contract, implementation, fresh check evidence, review and verified handoff."
+      item.mode = "primary"
+      item.system = undefined
+      item.color = "#e6c480"
+      item.permissions.push({ action: "question", resource: "*", effect: "allow" })
+    })
+    editor.update(LITE_AGENT_ID, item => {
+      item.name = "Lite" as unknown as typeof item.name
+      item.description = "Direct execution with existing skills and tools. No delivery harness."
+      item.mode = "primary"
+      item.color = "#b89ce0"
+      item.system = "You are a direct execution agent. Use the skills and tools already available and work the task directly. No extra planning ceremony, no harness phases — just do the work well and concisely."
+      item.permissions.push({ action: "question", resource: "*", effect: "allow" })
+    })
+    editor.default(SHIP_AGENT_ID)
+  })
+  return async () => { await registration.dispose() }
+}
+
+function frontmatter(raw: string) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!match) return { fields: {} as Record<string, string>, body: raw }
+  const fields: Record<string, string> = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/)
+    if (field) fields[field[1]] = field[2].trim().replace(/^["']|["']$/g, "")
+  }
+  return { fields, body: raw.slice(match[0].length) }
+}
+
+export function bundledSkills(root = SKILLS_ROOT) {
+  if (!existsSync(root)) return []
+  return readdirSync(root, { withFileTypes: true }).filter(entry => entry.isDirectory()).flatMap(entry => {
+    const path = join(root, entry.name, "SKILL.md")
+    if (!existsSync(path)) return []
+    const { fields, body } = frontmatter(readFileSync(path, "utf8"))
+    return [{ id: entry.name, name: fields.name || entry.name, ...(fields.description ? { description: fields.description } : {}), path, content: body }]
+  })
+}
+
+/** Legacy runs passed `--skill skills/`; the native host receives the same skill set. */
+export async function registerShipSkills(ctx: Pick<Context, "skill">, root = SKILLS_ROOT) {
+  const skills = bundledSkills(root)
+  const registration = await ctx.skill.transform((editor: SkillEditor) => {
+    for (const skill of skills) if (!editor.get(skill.id)) editor.add(skill as Parameters<SkillEditor["add"]>[0])
+  })
+  return async () => { await registration.dispose() }
+}

package/plugins/carthagent/src/server/ship-context.mjs

@@ -0,0 +1,60 @@
+import { archiveContext } from '../../../../lib/context-archive.mjs';
+
+const DELIVERY = new Set(['delivery_plan', 'delivery_revise', 'delivery_design', 'delivery_status', 'delivery_progress', 'delivery_check', 'delivery_review']);
+export const localToolName = name => String(name).replace(/^carthagent[._]/, '');
+const blocking = value => /"severity"\s*:\s*"blocking"|"passed"\s*:\s*false/.test(JSON.stringify(value).replaceAll('\\"', '"'));
+
+// Native results can group multiple calls in one message. Never split a call/result
+// pair or discard other content on the assistant/result messages when archiving.
+export function archiveDeliveryExchanges(messages, { cwd, directory, allow = false, keepRecent = 2 }) {
+  if (!allow) return { messages, failed: false };
+  const groups = [];
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+    if (message.role !== 'assistant' || !message.content?.length || message.content.some(part => part.type !== 'tool-call' || !DELIVERY.has(localToolName(part.name)))) continue;
+    const ids = new Set(message.content.map(part => part.id));
+    if (ids.has(undefined) || ids.size !== message.content.length) continue;
+    let end = i + 1;
+    const results = [];
+    while (end < messages.length && messages[end].role === 'tool') {
+      results.push(...messages[end].content);
+      end++;
+      if (results.length >= ids.size) break;
+    }
+    if (results.length !== ids.size || results.some(part => part.type !== 'tool-result' || !ids.has(part.id) || part.result?.type === 'error' || blocking(part.result))) continue;
+    if (new Set(results.map(part => part.id)).size !== ids.size) continue;
+    groups.push({ start: i, end, tools: message.content.map(part => part.name) });
+    i = end - 1;
+  }
+  const replace = new Map(); let failed = false;
+  for (const group of groups.slice(0, Math.max(0, groups.length - keepRecent))) {
+    try {
+      const archive = archiveContext(cwd, directory, messages.slice(group.start, group.end));
+      replace.set(group.start, { ...group, archive });
+    } catch { failed = true; }
+  }
+  const projected = [];
+  for (let i = 0; i < messages.length;) {
+    const group = replace.get(i);
+    if (!group) { projected.push(messages[i++]); continue; }
+    projected.push({ role: 'user', content: [{ type: 'text', text: `Archived successful delivery exchange (not proof of correctness). Tools: ${group.tools.join(', ')}. Read ${group.archive.path} for original messages; sha256=${group.archive.digest}. Current obligations/failures are in the delivery recovery record.` }] });
+    i = group.end;
+  }
+  return { messages: projected, failed };
+}
+
+export function normalizeDesignReview(input) {
+  const review = input.review ?? { challenges: input.challenges, walkthroughs: input.walkthroughs, findings: input.findings, limitations: input.limitations };
+  return { ...review, captureId: review.captureId ?? input.captureId ?? review.id };
+}
+
+export function shellProtection(command, initialFiles) {
+  const broad = /\b(?:pkill|killall)\b|\bkill\s+(?:-\S+\s+)*(?:-1|0)(?:\s|$)|\btaskkill\b[^\n]*(?:\/im|\*)|\bstop-process\b[^\n]*\s-name\b|\bget-process\b[^\n]*\|\s*stop-process\b/i;
+  if (broad.test(command)) return 'Broad process termination is blocked. Stop only the specific PID/process you started.';
+  for (const file of initialFiles) {
+    const escaped = file.split(/[\\/]/).at(-1).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (new RegExp(`(?:>|tee\\s+)\\s*["']?[^\\s;|]*${escaped}(?:["'\\s;|]|$)`).test(command)) return 'Shell redirection cannot overwrite an existing source file. Use a focused edit.';
+    if (/writeFile|write_text|write_bytes/.test(command) && command.includes(file.split(/[\\/]/).at(-1))) return 'A script cannot replace an existing source file. Use a focused edit.';
+    if (new RegExp(`(?:^|[;&|]\\s*)(?:rm|mv|cp)\\s+[^;|]*${escaped}(?:["'\\s;|]|$)`).test(command)) return 'Shell commands cannot remove or replace an existing source file. Use a focused edit.';
+  }
+}

package/plugins/carthagent/src/server/ship-guidance.ts

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { DELIVERY_INVARIANTS, TEST_INFRASTRUCTURE_GUIDANCE, deliveryPhaseGuidance } from "../../../../lib/delivery-guidance.mjs"
+import { PLANNING_START } from "../../../../lib/planning-guide.mjs"
+import { formatGuidance } from "../../../../lib/guidance.mjs"
+import { looksInformational } from "../../../../lib/delivery.mjs"
+import { unframe } from "./framing.mjs"
+
+export const STANDARD_GUIDANCE = "Standard delivery: inspect relevant files (glob/read/code_nav); create delivery_plan with complete requirements, artifact roots, a few steps and real checks. A valid required plan enables implementation immediately: design components/scenario ceremony is optional. Revisions merge design/workflow fields, replace supplied arrays, preserve obligations and require fresh final evidence, not repeated approval. Mark implementation steps done independently of integrated check execution. Use delivery_check all, final delivery_review inspect/record, then delivery_finish with honest limitations. No fabricated evidence, scope reduction or unrequested dependency changes. Informational plans do not authorize implementation. For bounded environment versions use delivery_probe kind=node-version or npm-version; inspect other APIs through read."
+
+export const TOOL_SURFACE_GUIDANCE = "File edits and commands use the direct read/write/edit/bash tools. A code-mode search() catalog lists only namespaced tools.* helpers, so their absence there does not mean they are unavailable. If a tool is locked, its error names the required delivery step; take that step instead of searching for alternatives."
+
+const browserCheck = fileURLToPath(new URL("../../../../tools/browser-check.mjs", import.meta.url))
+const browserGuidance = existsSync(browserCheck)
+  ? `For web/browser tasks, a self-contained browser check is available: ${JSON.stringify(browserCheck)}. Declare it as a runtime check, e.g. ["node",${JSON.stringify(browserCheck)},"--page","index.html","--assert","#app","--assert-count","#items:3","--click","#btn","--then-text","#out:done","--console-clean","--screenshot","artifacts/ui.png"]. It serves the workspace over HTTP, runs jsdom assertions with real inline-script execution (clicks, text, selectors, console-error detection), and captures a real screenshot with the bundled lightweight headless browser (auto-downloaded on first use).`
+  : ""
+
+export function originalTask(prompt: string) { return unframe(prompt) ?? prompt }
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- Host-neutral domain snapshots are JS objects. */
+export function shipGuidance({ state, workflow, prompt = "", profiles = [], discovery, extraGuidance, required = [], imageInput }: {
+  state: any; workflow: string; prompt?: string; profiles?: any[]; discovery?: any;
+  extraGuidance?: string; required?: any[]; imageInput?: boolean;
+}) {
+/* eslint-enable @typescript-eslint/no-explicit-any */
+  const task = originalTask(prompt)
+  const mode = state && !["verified", "blocked"].includes(state.status) ? state.workflowMode : workflow
+  const parts = mode === "standard"
+    ? ["Preserve every user requirement and promised output.", STANDARD_GUIDANCE, TOOL_SURFACE_GUIDANCE]
+    : [DELIVERY_INVARIANTS, deliveryPhaseGuidance(state), TOOL_SURFACE_GUIDANCE]
+  if (/\b(test|typescript|route|backend|api)\b/i.test(task)) parts.push(TEST_INFRASTRUCTURE_GUIDANCE)
+  if (profiles.some(profile => /web|browser/.test(profile.id)) || /\b(browser|web|frontend|screenshot)\b/i.test(task)) parts.push(browserGuidance)
+  if (imageInput === false) parts.push("This session's model cannot process images: do not attempt to view, read, or reason over image files or screenshots — visual review is unavailable. Verify visual behavior through DOM structure, computed styles, and console evidence instead; screenshots remain useful as evidence artifacts for the user even though you cannot inspect them.")
+  if (discovery?.active && mode !== "standard") parts.push(PLANNING_START)
+  const routed = formatGuidance(profiles)
+  if (routed) parts.push(routed)
+  if (extraGuidance) parts.push(`Task-specific delivery context:\n${extraGuidance}`)
+  if (required.length) parts.push(`User-owned required validators will be added to your plan automatically: ${JSON.stringify(required)}. Run delivery_check id="all"; repair failures rather than replacing or bypassing these checks.`)
+  if (looksInformational(task)) parts.push('Receipt check: this prompt reads as informational/read-only. Answer it directly, or if you record a contract use delivery_plan verification:"none" (no checks) or "advisory" (optional non-blocking evidence). Do not enter the verify/repair loop for a pure question — decide the classification now, before the verify loop.')
+  return parts.filter(Boolean).join("\n\n")
+}

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

@@ -0,0 +1,69 @@
+import { CloudClient, cloudControlUrl } from '../../../../lib/cloud/client.mjs';
+import type { Context } from '@opencode/plugin/promise/plugin';
+import type { ConnectionInfo } from '@opencode/client';
+
+type ShipContext = Pick<Context, 'integration'>;
+type ActiveCredential = Extract<ConnectionInfo, { type: 'credential' }>;
+type CloudClientPort = Pick<CloudClient, 'account' | 'usage' | 'checkout' | 'portal' | 'revokeCurrent' | 'revokeSession'>;
+
+/** Create profile-scoped Ship RPC handlers; injection keeps cloud behavior testable offline. */
+export function createShipRpcHandlers(ctx: ShipContext, options: {
+  cloudClient?: CloudClientPort;
+  baseUrl?: string;
+  cloudUrl?: string;
+} = {}) {
+  const cloud = options.cloudClient ?? new CloudClient({ baseUrl: options.baseUrl ?? cloudControlUrl() });
+  async function access() {
+    const active = await ctx.integration.connection.active('experiential-labs');
+    if (!active || active.type !== 'credential' || active.method !== 'oauth') throw new Error('An active Carthagent Ship OAuth connection is required.');
+    const credential = await ctx.integration.connection.resolve(active);
+    if (credential?.type !== 'oauth' || credential.methodID !== 'carthagent-device' || !credential.access) {
+      throw new Error('An active Carthagent Ship OAuth connection is required.');
+    }
+    return { active: active as ActiveCredential, token: credential.access };
+  }
+  return {
+    shipAccount: async (_input: unknown, call: import('@opencode/plugin/promise/rpc').RpcCallContext<typeof import('../rpc').Carthagent.methods.shipAccount>) => {
+      call.signal.throwIfAborted();
+      let token: string;
+      try { ({ token } = await access()); }
+      catch { return call.error('unauthenticated', 'An active Carthagent Ship OAuth connection is required.', {}); }
+      return { account: await cloud.account({ accessToken: token, signal: call.signal }) };
+    },
+    shipUsage: async (input: unknown, call: { signal: AbortSignal }) => {
+      call.signal.throwIfAborted();
+      const { token } = await access();
+      const requested = (input as { limit?: number }).limit ?? 50;
+      if (!Number.isSafeInteger(requested) || requested < 1 || requested > 200) throw new Error('Ship usage limit must be between 1 and 200.');
+      return { usage: await cloud.usage({ accessToken: token, limit: requested, signal: call.signal } as Parameters<CloudClient['usage']>[0]) };
+    },
+    shipBilling: async (input: unknown, call: import('@opencode/plugin/promise/rpc').RpcCallContext<typeof import('../rpc').Carthagent.methods.shipBilling>) => {
+      call.signal.throwIfAborted();
+      let token: string;
+      try { ({ token } = await access()); }
+      catch { return call.error('unauthenticated', 'An active Carthagent Ship OAuth connection is required.', {}); }
+      const action = (input as { action: 'checkout' | 'portal' }).action;
+      if (action !== 'checkout' && action !== 'portal') throw new Error('Unsupported Ship billing action.');
+      const returnUrl = `${options.cloudUrl ?? cloudControlUrl()}/account`;
+      const result = action === 'portal'
+        ? await cloud.portal({ accessToken: token, returnUrl, signal: call.signal })
+        : await cloud.checkout({ accessToken: token, successUrl: returnUrl, cancelUrl: returnUrl, signal: call.signal });
+      return { url: result.url };
+    },
+    shipLogout: async (input: unknown, call: import('@opencode/plugin/promise/rpc').RpcCallContext<typeof import('../rpc').Carthagent.methods.shipLogout>) => {
+      call.signal.throwIfAborted();
+      let active: ActiveCredential;
+      let token: string;
+      try { ({ active, token } = await access()); }
+      catch { return call.error('unauthenticated', 'An active Carthagent Ship OAuth connection is required.', {}); }
+      const session = (input as { session?: string }).session;
+      if (session) {
+        await cloud.revokeSession({ accessToken: token, sessionId: session, signal: call.signal });
+        return { revoked: true };
+      }
+      await cloud.revokeCurrent({ accessToken: token, signal: call.signal });
+      await ctx.integration.transform((editor) => editor.remove(active.id));
+      return { revoked: true, credentialID: active.id };
+    },
+  };
+}