carthagent 0.0.0-stage → 1.0.7

package/lib/tui/title.mjs

@@ -0,0 +1,7 @@
+import { basename } from 'node:path';
+
+export function terminalTitleSequence(cwd) {
+  // Folder names must not inject terminal controls into the OSC title.
+  const folder = basename(cwd).replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+  return `\x1b]0;Carthagent${folder ? ` - ${folder}` : ''}\x07`;
+}

package/lib/update-channel.mjs

@@ -0,0 +1,62 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+export const UPDATE_CHANNELS = ['stable', 'beta', 'experimental'];
+
+export function validateUpdateChannel(channel) {
+  if (!UPDATE_CHANNELS.includes(channel)) throw Error(`Invalid update channel: ${channel}. Choose stable, beta, or experimental.`);
+  return channel;
+}
+
+export function updateChannelPath(env = process.env) {
+  return env.CARTHAGENT_UPDATE_CHANNEL_FILE || join(env.HOME || env.USERPROFILE || homedir(), '.carthagent', 'update-channel.json');
+}
+
+export function readUpdateChannel(env = process.env) {
+  try {
+    const value = JSON.parse(readFileSync(updateChannelPath(env), 'utf8'));
+    if (value.version !== 1) throw Error('Unsupported update channel file version');
+    return validateUpdateChannel(value.channel);
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'stable';
+    throw Error(`Cannot read update channel; use ctg update --channel stable to reset it: ${error.message}`);
+  }
+}
+
+export function writeUpdateChannel(channel, env = process.env) {
+  validateUpdateChannel(channel);
+  const path = updateChannelPath(env);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify({ version: 1, channel }) + '\n', { mode: 0o600, flag: 'wx' });
+    renameSync(temp, path);
+  } finally { rmSync(temp, { force: true }); }
+}
+
+export function parseUpdateOptions(args) {
+  const options = { checkOnly: false, force: false, channel: null };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--check') options.checkOnly = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--channel' || arg.startsWith('--channel=')) {
+      if (options.channel !== null) throw Error('Specify --channel only once.');
+      options.channel = validateUpdateChannel(arg === '--channel' ? args[++i] : arg.slice('--channel='.length));
+    } else throw Error(`Unknown update option: ${arg}`);
+  }
+  return options;
+}
+
+export function releaseAllowedOnChannel(release, channel) {
+  validateUpdateChannel(channel);
+  if (!release || release.draft || typeof release.version !== 'string') return false;
+  const version = release.version.split('+')[0];
+  const label = version.includes('-') ? version.slice(version.indexOf('-') + 1) : '';
+  if (!label && !release.prerelease) return true;
+  if (channel === 'stable') return false;
+  if (channel === 'experimental') return true;
+  return /^(beta|rc)(\.|$)/.test(label || '');
+}

package/lib/update.mjs

@@ -0,0 +1,230 @@
+/**
+ * Self-update support for `ctg update` and the passive once-a-day console notice.
+ *
+ * Release resolution order:
+ *   1. Control plane  GET <CARTHAGENT_CLOUD_URL|api.carthagent.xyz>/v1/cli/releases/latest
+ *      (operator-controlled "latest" pointer — staged rollouts, pullbacks)
+ *   2. GitHub releases API for B-icy/Carthagent — fallback while the endpoint is
+ *      unconfigured (503/404) or unreachable.
+ *
+ * Install methods:
+ *   - clone  : the package root contains .git (installed via `npm install -g .` from a
+ *              clone) → checkout the tag in place, `npm ci`, re-link.
+ *   - npm    : global `github:` install → `npm install -g --install-links=true <spec>`.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import { cloudControlUrl } from './cloud/client.mjs';
+import { shipAgentDir } from './ship-auth.mjs';
+import { installPingHeaders } from './ship-telemetry.mjs';
+import { readUpdateChannel, releaseAllowedOnChannel, validateUpdateChannel } from './update-channel.mjs';
+
+export const GITHUB_REPO = 'B-icy/Carthagent';
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The installed package version (package.json next to lib/). */
+export function packageVersion() {
+  try { return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version; }
+  catch { return null; }
+}
+
+/** Semver-ish ordering: numeric triple, then a release outranks its prereleases. */
+export function compareVersions(a, b) {
+  const parse = value => {
+    const m = String(value || '').trim().replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+    if (!m) return null;
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || '' };
+  };
+  const left = parse(a), right = parse(b);
+  if (!left || !right) throw new Error(`cannot compare versions '${a}' and '${b}'`);
+  for (let i = 0; i < 3; i++) if (left.nums[i] !== right.nums[i]) return left.nums[i] - right.nums[i];
+  if (left.pre === right.pre) return 0;
+  if (!left.pre) return 1;
+  if (!right.pre) return -1;
+  const lp = left.pre.split('.'), rp = right.pre.split('.');
+  for (let i = 0; i < Math.max(lp.length, rp.length); i++) {
+    if (lp[i] === undefined) return -1;
+    if (rp[i] === undefined) return 1;
+    if (lp[i] === rp[i]) continue;
+    const ln = /^\d+$/.test(lp[i]), rn = /^\d+$/.test(rp[i]);
+    if (ln && rn) return Number(lp[i]) - Number(rp[i]);
+    if (ln !== rn) return ln ? -1 : 1; // numeric identifiers rank below alphanumeric
+    return lp[i] < rp[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Normalize a control-plane or GitHub releases payload into the manifest shape. */
+export function normalizeRelease(raw, { githubRepo = GITHUB_REPO } = {}) {
+  if (!raw || typeof raw !== 'object' || raw.draft === true) return null;
+  if (['draft', 'prerelease'].some(key => raw[key] !== undefined && typeof raw[key] !== 'boolean')) return null;
+  // GitHub releases/latest shape: { tag_name, name, published_at, body }
+  const suppliedTag = raw.tag ?? raw.tag_name;
+  if (suppliedTag !== undefined && (typeof suppliedTag !== 'string' || suppliedTag.length === 0)) return null;
+  const tag = suppliedTag ?? '';
+  const suppliedVersion = raw.version;
+  if (suppliedVersion !== undefined && (typeof suppliedVersion !== 'string' || suppliedVersion.length === 0)) return null;
+  const version = suppliedVersion ?? tag.replace(/^v/, '');
+  if (!SEMVER_RE.test(version)) return null;
+  // Never let a valid version select a different mutable ref (for example
+  // `main`, another release, or a whitespace/URL-encoded ref). The only
+  // accepted release tag is the canonical tag for this exact version.
+  const expectedTag = `v${version}`;
+  if (tag && tag !== expectedTag) return null;
+  // The manifest is an install instruction: `ctg update` runs
+  // `npm install -g <installSpec>` verbatim. Pin it to this release's tag on
+  // the canonical repo so a leaked publish token cannot redirect installs.
+  const canonicalTag = expectedTag;
+  const installSpec = `github:${githubRepo}#${canonicalTag}`;
+  if (raw.installSpec !== undefined && (typeof raw.installSpec !== 'string' || raw.installSpec !== installSpec)) return null;
+  return {
+    version,
+    prerelease: raw.prerelease === true || version.split('+')[0].includes('-'),
+    tag: canonicalTag,
+    installSpec,
+    minNode: String(raw.minNode || '22.19.0').trim(),
+    note: typeof raw.note === 'string' && raw.note.trim() ? raw.note.trim()
+      : typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : undefined,
+    publishedAt: raw.publishedAt || raw.published_at || undefined,
+  };
+}
+
+/** Latest release manifest: control plane first, GitHub releases as fallback. */
+export async function fetchLatestRelease({ cloudUrl = cloudControlUrl(), githubRepo = GITHUB_REPO, fetchImpl = globalThis.fetch, timeoutMs = 8000, env = process.env, agentDir = shipAgentDir(env), signal, channel = readUpdateChannel(env) } = {}) {
+  validateUpdateChannel(channel);
+  const getJson = async (url, headers = {}) => {
+    signal?.throwIfAborted();
+    const res = await fetchImpl(url, {
+      headers: { accept: 'application/json', 'user-agent': `carthagent-cli`, ...headers },
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+    });
+    const body = await res.json().catch(() => null);
+    return { status: res.status, body };
+  };
+  if (channel !== 'stable') {
+    const candidates = [];
+    for (let page = 1; page <= 10; page++) {
+      const { status, body } = await getJson(`https://api.github.com/repos/${githubRepo}/releases?per_page=100&page=${page}`);
+      if (status !== 200 || !Array.isArray(body)) throw Error(`GitHub ${channel} release listing failed (${status}).`);
+      for (const item of body) {
+        const release = normalizeRelease(item, { githubRepo });
+        if (releaseAllowedOnChannel(release, channel)) candidates.push(release);
+      }
+      if (body.length < 100) {
+        candidates.sort((a, b) => compareVersions(b.version, a.version));
+        if (!candidates.length) throw Error(`No published releases are available on the ${channel} channel.`);
+        return { release: candidates[0], source: 'github' };
+      }
+    }
+    throw Error('GitHub release listing exceeded 1,000 entries; refusing an incomplete channel selection.');
+  }
+  try {
+    // The release check doubles as the anonymous install ping; GitHub never
+    // sees these headers.
+    const { status, body } = await getJson(`${String(cloudUrl).replace(/\/+$/, '')}/v1/cli/releases/latest`, installPingHeaders({ env, agentDir, version: packageVersion() }));
+    if (status === 200) {
+      const release = normalizeRelease(body, { githubRepo });
+      if (releaseAllowedOnChannel(release, channel)) return { release, source: 'control-plane' };
+      // A 200 manifest that fails validation (e.g. a mismatched installSpec)
+      // must not dead-end the update — resolve the GitHub release instead.
+    } else if (![404, 503].includes(status)) throw new Error(`control plane returned ${status}`);
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (!/control plane|fetch|network|abort|timed? ?out|connect|socket/i.test(error?.message || String(error))) throw error;
+    // unreachable/unconfigured control plane → fall through to GitHub
+  }
+  signal?.throwIfAborted();
+  const { status, body } = await getJson(`https://api.github.com/repos/${githubRepo}/releases/latest`);
+  if (status !== 200) throw new Error(status === 404 ? 'no tagged GitHub release exists yet' : `GitHub releases returned ${status}`);
+  const release = normalizeRelease(body, { githubRepo });
+  if (!releaseAllowedOnChannel(release, channel)) throw new Error('GitHub latest release is not a valid stable release.');
+  return { release, source: 'github' };
+}
+
+/** 'clone' when the running package root is a git checkout, else 'npm'. */
+export function detectInstallMethod(root) {
+  return existsSync(join(root, '.git')) ? 'clone' : 'npm';
+}
+
+/**
+ * Entries under a global node_modules dir that break `npm install -g` with
+ * ENOTDIR/EEXIST: a non-directory `carthagent` entry (stray file or dangling
+ * symlink from an earlier `npm link`) and `.carthagent-*` stash paths npm
+ * abandons when an install is interrupted mid-swap.
+ */
+export function staleGlobalInstallPaths(npmRoot) {
+  const stale = [];
+  const entry = join(npmRoot, 'carthagent');
+  try {
+    if (!lstatSync(entry).isDirectory()) stale.push(entry);
+  } catch { /* absent */ }
+  let names = [];
+  try { names = readdirSync(npmRoot); } catch { /* unreadable */ }
+  for (const name of names) if (/^\.carthagent-.+/.test(name)) stale.push(join(npmRoot, name));
+  return stale;
+}
+
+/** Remove stale install leftovers; returns the paths it deleted. */
+export function cleanStaleGlobalInstall(npmRoot) {
+  const removed = [];
+  for (const path of staleGlobalInstallPaths(npmRoot)) {
+    try { rmSync(path, { recursive: true, force: true }); removed.push(path); }
+    catch { /* best-effort */ }
+  }
+  return removed;
+}
+
+/** Passive-check cache (~/.carthagent/update-check.json). */
+export function updateCheckPath(env = process.env) {
+  return env.CARTHAGENT_UPDATE_CHECK_FILE || join(os.homedir(), '.carthagent', 'update-check.json');
+}
+
+export function updateCheckEnabled(env = process.env) {
+  const off = env.CARTHAGENT_NO_UPDATE_CHECK || env.CARTHAGENT_UPDATE_CHECK === '0' || env.CARTHAGENT_UPDATE_CHECK === 'false';
+  return !off;
+}
+
+export function readUpdateCache(path = updateCheckPath()) {
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return data && typeof data === 'object' ? data : null;
+  } catch { return null; }
+}
+
+export function writeUpdateCache(entry, path = updateCheckPath()) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(entry));
+    renameSync(tmp, path);
+  } catch { /* cache is best-effort */ }
+}
+
+/**
+ * Latest release for the passive notice, throttled to one fetch per day.
+ * Cache writes happen on every attempt (success or failure) so a failing
+ * network doesn't get retried every launch.
+ */
+export async function latestReleaseCached({ cachePath = updateCheckPath(), now = Date.now(), intervalMs = UPDATE_CHECK_INTERVAL_MS, env = process.env, channel = readUpdateChannel(env), ...fetchOpts } = {}) {
+  validateUpdateChannel(channel);
+  const cached = readUpdateCache(cachePath);
+  const sameChannel = (cached?.channel ?? 'stable') === channel;
+  const normalized = normalizeRelease(cached?.release);
+  const staleRelease = sameChannel && releaseAllowedOnChannel(normalized, channel) ? normalized : null;
+  if (sameChannel && (!cached?.release || staleRelease) && cached && Number.isFinite(cached.checkedAt) && now - cached.checkedAt < intervalMs) {
+    return { release: staleRelease, fresh: true };
+  }
+  try {
+    const { release, source } = await fetchLatestRelease({ ...fetchOpts, env, channel });
+    writeUpdateCache({ checkedAt: now, release, source, channel }, cachePath);
+    return { release, fresh: false };
+  } catch {
+    writeUpdateCache({ checkedAt: now, release: staleRelease, channel }, cachePath);
+    return { release: staleRelease, fresh: false };
+  }
+}

package/lib/webdriver.mjs

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { captureBrowserErrors } from './browser-errors.mjs';
+
+/** Bounded W3C WebDriver checks with mandatory pre-navigation BiDi error capture. */
+export async function webdriverCheck({ endpoint, url, steps = [], screenshot, waitMs = 5000 }) {
+  if (!Number.isInteger(waitMs) || waitMs < 1 || waitMs > 60000) throw Object.assign(Error('waitMs must be an integer from 1 to 60000'), { category: 'configuration' });
+  let deadline;
+  let phase = 'driver';
+  let stepIndex;
+  let currentStep;
+  const base = endpoint.replace(/\/$/, '');
+  async function request(path, method = 'GET', body) {
+    const response = await fetch(base + path, {
+      method, headers: { 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(deadline ? Math.max(1, Math.min(20000, deadline - Date.now())) : 20000)
+    });
+    const data = await response.json();
+    if (!response.ok || data.value?.error) throw Object.assign(Error(data.value?.message || `WebDriver HTTP ${response.status}`), { webdriverCode: data.value?.error });
+    return data.value;
+  }
+  const session = await request('/session', 'POST', { capabilities: { alwaysMatch: {
+    browserName: 'firefox', webSocketUrl: true, 'moz:firefoxOptions': { args: ['-headless'] }
+  } } });
+  const prefix = `/session/${session.sessionId}`;
+  let failure;
+  let capture;
+  let diagnostics;
+  try {
+    phase = 'capture';
+    capture = await captureBrowserErrors(session.capabilities.webSocketUrl);
+    await request(prefix + '/timeouts', 'POST', { implicit: 0, pageLoad: 15000, script: 5000 });
+    phase = 'navigation';
+    await request(prefix + '/url', 'POST', { url });
+    for (const [index, step] of steps.entries()) {
+      phase = 'assertion'; stepIndex = index; currentStep = step;
+      deadline = Date.now() + waitMs;
+      let id;
+      for (;;) {
+        try {
+          const element = await request(prefix + '/element', 'POST', { using: 'css selector', value: step.selector });
+          id = element['element-6066-11e4-a52e-4f735466cecf'];
+          if (step.text !== undefined) {
+            const text = await request(`${prefix}/element/${id}/text`);
+            if (!text.includes(step.text)) throw Object.assign(Error(`${step.selector}: expected ${JSON.stringify(step.text)}, got ${JSON.stringify(text)}`), { webdriverCode: 'text mismatch' });
+          }
+          break;
+        } catch (error) {
+          if (!['no such element', 'stale element reference', 'text mismatch'].includes(error.webdriverCode) || Date.now() >= deadline) throw error;
+          await new Promise(r => setTimeout(r, Math.min(100, Math.max(1, deadline - Date.now()))));
+        }
+      }
+      deadline = undefined;
+      if (step.action === 'click') {
+        phase = 'interaction';
+        await request(`${prefix}/element/${id}/click`, 'POST', {});
+      }
+    }
+    stepIndex = undefined; currentStep = undefined; phase = 'screenshot';
+    if (screenshot) {
+      const png = await request(prefix + '/screenshot');
+      mkdirSync(dirname(screenshot), { recursive: true });
+      writeFileSync(screenshot, Buffer.from(png, 'base64'));
+    }
+  } catch (error) {
+    failure = Object.assign(error, { category: phase, stepIndex, selector: currentStep?.selector, expected: currentStep?.text });
+  }
+  deadline = undefined;
+  if (capture) {
+    try {
+      diagnostics = await capture.inspect();
+      if (diagnostics.errors.length) failure ||= Object.assign(Error('Unexpected browser errors'), { category: 'browser-errors' });
+    } catch (error) { failure ||= Object.assign(error, { category: 'capture' }); }
+    finally { capture.close(); }
+  }
+  if (failure && diagnostics) Object.assign(failure, { browserErrors: diagnostics.errors, droppedBrowserErrors: diagnostics.dropped });
+  try { await request(prefix, 'DELETE'); }
+  catch (error) { failure ||= Object.assign(Error(`Session cleanup failed: ${error.message}`), { category: 'cleanup' }); }
+  if (failure) throw failure;
+  return { pass: true, engine: 'firefox-webdriver', browserVersion: session.capabilities.browserVersion, screenshot: screenshot || null, consoleChecked: true };
+}

package/lib/workflow.mjs

@@ -0,0 +1,88 @@
+// Canonical, non-executable workflow data. Models propose nodes and branches;
+// harness policy remains authoritative. No renderer or process dependencies.
+const list = v => Array.isArray(v) ? v : [];
+const text = v => typeof v === 'string' && v.trim().length > 0;
+const safe = v => text(v) && /^[a-z][a-z0-9_-]{0,39}$/.test(v) && !v.startsWith('gate_');
+export function validateWorkflow(plan) {
+  if (plan.workflow === undefined) return []; // Legacy plans have a projection.
+  const errors = [], workflow = plan.workflow;
+  const fail = message => errors.push({ code: 'workflow', target: 'workflow', severity: 'blocking', message });
+  if (!workflow || typeof workflow !== 'object' || !Array.isArray(workflow.nodes) || !Array.isArray(workflow.recovery)) { fail('Workflow requires nodes and recovery arrays.'); return errors; }
+  if (!workflow.nodes.length || workflow.nodes.length > 80) fail('Workflow requires 1–80 nodes.');
+  if (workflow.recovery.length > 80) fail('Use at most 80 recovery transitions.');
+  const ids = new Set(), steps = new Set(list(plan.steps).map((s, i) => typeof s === 'string' ? `legacy_${i + 1}` : s.id));
+  const components = new Set(list(plan.design?.components).map(c => c?.id));
+  const checks = new Set(list(plan.checks).map(c => c.id));
+  const requirements = new Set(list(plan.acceptance).map(a => a.requirement));
+  for (const n of workflow.nodes) {
+    if (!n || !safe(n.id) || ids.has(n.id)) { fail('Node IDs must be unique safe IDs outside the gate_ namespace.'); continue; }
+    ids.add(n.id);
+    if (!text(n.title) || n.title.length > 500 || !['work', 'decision', 'check', 'artifact'].includes(n.type)) fail(`Invalid title/type: ${n.id}`);
+    for (const field of ['dependsOn', 'requirements', 'components', 'checks', 'inputs', 'artifacts', 'effects']) if (!Array.isArray(n[field]) || n[field].some(v => !text(v)) || new Set(n[field]).size !== n[field].length) fail(`${n.id}.${field} must be a unique string array.`);
+    if (list(n.requirements).some(id => !requirements.has(id)) || list(n.components).some(id => !components.has(id)) || list(n.checks).some(id => !checks.has(id))) fail(`Unknown requirement/component/check: ${n.id}`);
+    if (list(n.effects).some(effect => !['read', 'write', 'execute'].includes(effect))) fail(`Unknown permitted effect: ${n.id}`);
+    if (n.type === 'work' && !steps.has(n.step)) fail(`Work node needs a declared step: ${n.id}`);
+    if (n.type === 'check' && !list(n.checks).length) fail(`Check node needs check IDs: ${n.id}`);
+    if (n.type === 'decision' && !text(n.condition)) fail(`Decision needs a condition: ${n.id}`);
+  }
+  const visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) { fail(`Dependency cycle at ${id}; use bounded recovery transitions instead.`); return; }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of list(workflow.nodes.find(n => n?.id === id)?.dependsOn)) {
+      if (!ids.has(dep)) fail(`Unknown dependency ${dep}`); else visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  }
+  for (const id of ids) visit(id);
+  for (const r of workflow.recovery) {
+    if (!r || !ids.has(r.from) || !ids.has(r.to) || !text(r.when) || !text(r.stop) || !Number.isInteger(r.maxAttempts) || r.maxAttempts < 1 || r.maxAttempts > 10) fail('Recovery needs known endpoints, condition, stop reason and maxAttempts 1–10.');
+  }
+  for (const step of steps) if (!workflow.nodes.some(n => n?.type === 'work' && n.step === step)) fail(`Workflow omits step ${step}`);
+  return errors;
+}
+
+export function workflowGraph(plan) {
+  const errors = validateWorkflow(plan);
+  if (errors.length) throw Error(errors.map(e => e.message).join('\n'));
+  const steps = list(plan.steps);
+  const proposed = plan.workflow ? structuredClone(plan.workflow.nodes) : steps.map((s, i) => ({
+    id: `step${i}`, step: typeof s === 'string' ? `legacy_${i + 1}` : s.id, title: typeof s === 'string' ? s : s.title, type: 'work',
+    dependsOn: typeof s === 'string' ? (i ? [`step${i - 1}`] : []) : list(s.dependsOn).map(id => `step${steps.findIndex(other => other?.id === id)}`),
+    requirements: [], components: [], checks: typeof s === 'string' ? [] : list(s.checks), inputs: [], artifacts: [], effects: ['write'],
+  }));
+  const gates = [
+    { id: 'gate_design', title: 'Test + approve plan', type: 'gate' },
+    { id: 'gate_verify', title: 'Fresh checks + coverage', type: 'gate' },
+    { id: 'gate_review', title: 'Final snapshot review', type: 'gate' },
+    { id: 'gate_deliver', title: 'Complete handoff', type: 'gate' },
+  ];
+  const edges = [];
+  for (const n of proposed) for (const dep of n.dependsOn.length ? n.dependsOn : ['gate_design']) edges.push({ from: dep, to: n.id, kind: 'dependency' });
+  for (const n of proposed) if (!proposed.some(other => other.dependsOn.includes(n.id))) edges.push({ from: n.id, to: 'gate_verify', kind: 'dependency' });
+  if (!proposed.length) edges.push({ from: 'gate_design', to: 'gate_verify', kind: 'dependency' });
+  edges.push({ from: 'gate_verify', to: 'gate_review', kind: 'dependency' }, { from: 'gate_review', to: 'gate_deliver', kind: 'dependency' });
+  for (const r of list(plan.workflow?.recovery)) edges.push({ ...r, kind: 'recovery', label: `${r.when}; <=${r.maxAttempts}; stop: ${r.stop}` });
+  return { authored: Boolean(plan.workflow), nodes: [gates[0], ...proposed, ...gates.slice(1)], edges, semantics: 'Dependency DAG plus proposed bounded recovery; not an executable scheduler. Effects and conditions are declarations, not sandbox permissions.' };
+}
+
+export function workflowD2(plan, stepStatus = {}) {
+  const graph = workflowGraph(plan), steps = list(plan.steps);
+  const lines = ['direction: down'];
+  for (const n of graph.nodes) {
+    const index = steps.findIndex((s, i) => (typeof s === 'string' ? `legacy_${i + 1}` : s.id) === n.step);
+    const status = index < 0 ? '' : stepStatus[`step${index}`] || 'pending';
+    lines.push(`${n.id}: ${JSON.stringify(`${n.title}${status ? ` [${status}]` : ''}`)}`);
+  }
+  for (const e of graph.edges) lines.push(`${e.from} -> ${e.to}${e.label ? `: ${JSON.stringify(e.label)}` : ''}`);
+  return lines.join('\n') + '\n';
+}
+
+export function architectureGraph(plan) {
+  return {
+    nodes: list(plan.design?.components).map(c => ({ id: c.id, title: c.responsibility, layer: c.layer, excludes: c.excludes, requirements: c.requirements })),
+    edges: list(plan.design?.components).flatMap(c => list(c.dependencies).map(to => ({ from: c.id, to, kind: 'dependency' }))),
+    ports: structuredClone(list(plan.design?.ports)),
+  };
+}

package/lib/workspace.mjs

@@ -0,0 +1,39 @@
+import { mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, relative, resolve, isAbsolute } from 'node:path';
+import { atomicJson } from './delivery.mjs';
+
+export function lockWorkspace(cwd) {
+  const dir = join(cwd, '.harness');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'workspace.lock');
+  let fd;
+  try { fd = openSync(path, 'wx'); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw Error('Workspace busy: another delivery operation is active. Retry after it finishes; never remove this lock without confirming the writer has stopped.');
+    throw error;
+  }
+  try { writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })); }
+  catch (error) { closeSync(fd); unlinkSync(path); throw error; }
+  return () => { closeSync(fd); unlinkSync(path); };
+}
+
+export function activeReportPath(cwd) {
+  let pointer;
+  try { pointer = JSON.parse(readFileSync(join(cwd, '.harness', 'active.json'), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (pointer?.version !== 1 || typeof pointer.path !== 'string' || isAbsolute(pointer.path)) throw Error('Invalid active workspace report');
+  const path = resolve(cwd, pointer.path);
+  const rel = relative(join(cwd, '.harness'), path);
+  if (rel.startsWith('..') || isAbsolute(rel) || !rel.endsWith('report.json')) throw Error('Invalid active workspace report path');
+  return path;
+}
+
+// Called only while holding the workspace operation lock.
+export function selectReport(cwd, path) {
+  atomicJson(join(cwd, '.harness', 'active.json'), { version: 1, path: relative(cwd, path) });
+}
+
+export function assertActiveReport(cwd, path) {
+  const active = activeReportPath(cwd);
+  if (active && resolve(active) !== resolve(path)) throw Error('Delivery run was superseded in this workspace. Inspect delivery_status and create a new plan explicitly; stale operations were not replayed.');
+}

package/metadata.json

@@ -0,0 +1,8 @@
+{
+  "name": "Carthagent",
+  "description": "Evidence-driven software delivery, from plan to proof",
+  "requestFramePermissions": [],
+  "majorCapabilities": [
+    "MAJOR_CAPABILITY_SERVER_SIDE_GEMINI_API"
+  ]
+}

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "carthagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.7",
+  "workspaces": [
+    "plugins/carthagent"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "description": "Evidence-driven software delivery, from plan to proof",
+  "keywords": [
+    "carthagent",
+    "ai-agent",
+    "software-delivery",
+    "evidence-driven-delivery"
+  ],
+  "bin": {
+    "ctg": "./bin/ctg.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/B-icy/Carthagent"
+  },
+  "homepage": "https://github.com/B-icy/Carthagent#readme",
+  "bugs": "https://github.com/B-icy/Carthagent/issues",
+  "files": [
+    "bin",
+    "docs",
+    "extensions",
+    "guidance",
+    "lib",
+    "plugins",
+    "!plugins/**/node_modules/**",
+    "themes",
+    "prompts",
+    "public",
+    "scenarios/**/*.json",
+    "scenarios/**/*.md",
+    "scenarios/**/*.py",
+    "scenarios/**/*.txt",
+    "skills",
+    "tests/*.mjs",
+    "tests/*.py",
+    "tests/fixtures/archive-plugin",
+    "tools",
+    "vendor",
+    "evaluate.mjs",
+    "metadata.json",
+    "server.mjs"
+  ],
+  "scripts": {
+    "dev": "node server.mjs",
+    "start": "node server.mjs",
+    "ctg": "node bin/ctg.mjs",
+    "check": "node tools/check-syntax.mjs",
+    "typecheck": "npm run typecheck:legacy && npm run typecheck:native",
+    "typecheck:legacy": "tsc --noEmit --skipLibCheck --target ES2023 --module NodeNext --moduleResolution NodeNext --types node extensions/delivery.ts extensions/experiential.ts extensions/subscriptions.ts extensions/codegraph.ts types/pi-coding-agent.d.ts",
+    "typecheck:native": "tsc -p plugins/carthagent/tsconfig.json",
+    "lint": "eslint . && npm run typecheck",
+    "quality": "npm run lint && npm run build && npm test",
+    "test:browser": "node tools/test-webdriver.mjs",
+    "test:native-host": "node tools/test-native-host.mjs",
+    "test:native-package": "node tools/test-native-package.mjs",
+    "test:native-controls": "node tools/test-native-controls.mjs",
+    "test:native-outcomes": "node tools/test-native-outcomes.mjs",
+    "test:native-pty": "node tools/test-native-pty.mjs",
+    "build": "npm run check && npm run typecheck",
+    "test": "node --test tests/*.test.mjs",
+    "test:python": "node tools/test-python.mjs"
+  },
+  "dependencies": {
+    "@opencode/cli": "2.0.32",
+    "@opencode/client": "2.0.32",
+    "@opencode/plugin": "2.0.32",
+    "express": "^5.2.1",
+    "jiti": "^2.7.0",
+    "jsdom": "^30.0.1",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.22.6"
+  },
+  "overrides": {
+    "seroval": "1.6.9"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.3.0",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "8.57.0"
+  },
+  "allowScripts": {
+    "@opencode/cli@2.0.32": true
+  }
+}

package/plugins/carthagent/index.ts

@@ -0,0 +1,3 @@
+export { default } from './src/index';
+export { setupCarthagent } from './src/index';
+export { registerDelivery, registerCodegraph, registerNativeDelivery } from './src/server/native-delivery';

package/plugins/carthagent/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@carthagent/opencode-plugin",
+  "version": "2.0.0-beta.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/bootstrap.ts",
+    "./rpc": "./src/rpc.ts",
+    "./delivery": "./src/server/native-delivery.ts"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.32"
+  },
+  "peerDependencies": {
+    "@opencode/theme": "2.0.32",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
+    "solid-js": "1.9.12"
+  },
+  "devDependencies": {
+    "@opencode/theme": "2.0.32",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
+    "solid-js": "1.9.12",
+    "web-tree-sitter": "0.25.10"
+  }
+}