@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/test/integration/storage-architecture.test.mjs

@@ -0,0 +1,154 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { dispatchShellLine } from '../../src/commands/shell.js';
+import { createLocalSession, listLocalSessions, loadLocalSession, saveLocalSession } from '../../src/lib/local-sessions.js';
+import { createLocalSqliteDatabaseSync } from '../../src/local/sqlite.js';
+import { applyRuntimeMigrationsSync } from '../../src/local/migrations.js';
+import { finishRuntimeRun, pruneExpiredRuntimeState, runtimeDatabasePath, startRuntimeRun } from '../../src/local/runtime-store.js';
+
+const repoRoot = path.resolve(new URL('../..', import.meta.url).pathname);
+
+function fixture(t) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-storage-'));
+  t.after(() => fs.rmSync(base, { recursive: true, force: true }));
+  const home = path.join(base, 'home');
+  const projectA = path.join(base, 'project-a');
+  const projectB = path.join(base, 'project-b');
+  for (const root of [projectA, projectB]) {
+    fs.mkdirSync(path.join(root, '.agentsam'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.agentsam', 'config.json'), '{"schema_version":2}\n');
+  }
+  fs.mkdirSync(home);
+  return { base, home, projectA, projectB };
+}
+
+test('S1: a local shell boots and migrates SQLite without cloud configuration', (t) => {
+  const { home, projectA } = fixture(t);
+  const env = { ...process.env, HOME: home };
+  for (const key of ['CLOUDFLARE_API_TOKEN', 'AGENTSAM_API_KEY', 'SUPABASE_URL', 'DATABASE_URL']) delete env[key];
+  const result = spawnSync(process.execPath, [path.join(repoRoot, 'src/cli.js'), 'shell'], {
+    cwd: projectA, env, input: '/exit\n', encoding: 'utf8', timeout: 10_000,
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Interactive shell ready/);
+  assert.equal(fs.existsSync(runtimeDatabasePath(projectA)), true);
+  assert.equal(fs.existsSync(path.join(home, '.agentsam', 'sessions')), false);
+});
+
+test('S2-S4: cwd and model changes preserve project state; repository switch selects a new authority', async (t) => {
+  const { home, projectA, projectB } = fixture(t);
+  const child = path.join(projectA, 'src', 'agent');
+  fs.mkdirSync(child, { recursive: true });
+  assert.equal(runtimeDatabasePath(child), runtimeDatabasePath(projectA));
+
+  const session = createLocalSession({ cwd: child, title: 'Project A' }, { home });
+  const changedModel = saveLocalSession({ ...session, model_key: 'gemini:example' }, { home });
+  assert.equal(changedModel.id, session.id);
+  assert.equal(changedModel.project_root, projectA);
+  assert.equal(loadLocalSession(session.id, { home, cwd: projectA }).model_key, 'gemini:example');
+  assert.equal(loadLocalSession(session.id, { home, cwd: projectB }), null);
+
+  const runId = await startRuntimeRun({ projectRoot: projectA, model_key: 'test:model' });
+  let output = '';
+  const state = { cwd: child, projectRoot: projectA, home, session: changedModel, interactive: false, write(value) { output += value; } };
+  await dispatchShellLine('/logs', state);
+  assert.match(output, new RegExp(runId));
+  await dispatchShellLine(`/cd ${projectB}`, state);
+  assert.equal(state.cwd, projectB);
+  assert.equal(state.projectRoot, projectB);
+  assert.notEqual(state.session.id, session.id);
+  assert.equal(listLocalSessions({ home, cwd: projectA })[0].id, session.id);
+  assert.equal(listLocalSessions({ home, cwd: projectB })[0].id, state.session.id);
+  assert.equal(fs.existsSync(path.join(child, '.agentsam', 'data', 'agentsam.sqlite')), false);
+});
+
+test('S5: expiry cleanup removes transient digests and retains completed run receipts', async (t) => {
+  const { projectA } = fixture(t);
+  const runId = await startRuntimeRun({ cwd: projectA, model_key: 'test:model' });
+  await finishRuntimeRun({ cwd: projectA, id: runId, status: 'completed' });
+  const db = createLocalSqliteDatabaseSync(runtimeDatabasePath(projectA));
+  db.prepare(`INSERT INTO agentsam_context_digest
+    (id, digest_type, agent_run_id, source_hash, digest_hash, digest_text, expires_at_unix)
+    VALUES (?, 'session', ?, 'source', 'digest', 'expired', 1)`).run('ctx_expired', runId);
+  db.prepare('INSERT INTO agentsam_compaction_events (id, agent_run_id, expires_at_epoch) VALUES (?, ?, 1)').run('cmp_expired', runId);
+  db.close();
+
+  const pruned = await pruneExpiredRuntimeState({ cwd: projectA, nowUnix: 2 });
+  assert.deepEqual(pruned, { digests: 1, compactions: 1, approvals_expired: 0 });
+  const verified = createLocalSqliteDatabaseSync(runtimeDatabasePath(projectA));
+  assert.equal(verified.prepare('SELECT status FROM agentsam_agent_run WHERE id = ?').get(runId).status, 'completed');
+  assert.equal(verified.prepare('SELECT COUNT(*) AS n FROM agentsam_context_digest').get().n, 0);
+  verified.close();
+});
+
+test('S6-S7: connected Worker bindings do not move sessions or store credential values', (t) => {
+  const { home, projectA } = fixture(t);
+  const workerConfig = fs.readFileSync(path.join(repoRoot, 'apps/local-studio/backend/wrangler.jsonc'), 'utf8');
+  for (const binding of ['"d1_databases"', '"hyperdrive"', '"r2_buckets"', '"services"']) assert.match(workerConfig, new RegExp(binding));
+  assert.doesNotMatch(workerConfig, /"durable_objects"/);
+
+  const secret = 'storage_secret_do_not_persist_123';
+  const session = createLocalSession({
+    cwd: projectA, title: 'Safe project session', last_input: secret,
+    provider_state: { provider: 'openai', previous_response_id: 'resp_safe', api_key: secret, messages: [{ content: secret }] },
+    usage_snapshot: { current_context: { input_tokens: 20 }, credential: secret },
+    last_error: { code: 'failed', message: secret },
+  }, { home });
+  assert.equal(session.storage.runtime, 'sqlite');
+  assert.equal(session.storage.remote, null);
+  assert.equal(session.storage.capabilities.remote_shared_state, false);
+  assert.equal(session.storage.capabilities.distributed_actor_semantics, false);
+  assert.equal(session.last_input, null);
+  assert.equal(session.provider_state.api_key, undefined);
+  assert.doesNotMatch(fs.readFileSync(runtimeDatabasePath(projectA), 'utf8'), new RegExp(secret));
+  assert.equal(fs.statSync(runtimeDatabasePath(projectA)).mode & 0o777, 0o600);
+});
+
+test('S8: canonical migrations upgrade an older runtime database for project sessions', (t) => {
+  const { base, home, projectA } = fixture(t);
+  const oldMigrations = path.join(base, 'old-migrations');
+  fs.mkdirSync(oldMigrations);
+  fs.copyFileSync(path.join(repoRoot, 'migrations/runtime/0001_cli_runtime.sql'), path.join(oldMigrations, '0001_cli_runtime.sql'));
+  const db = createLocalSqliteDatabaseSync(runtimeDatabasePath(projectA));
+  assert.equal(applyRuntimeMigrationsSync(db, { migrationsDir: oldMigrations }).applied, 1);
+  assert.equal(db.prepare("SELECT name FROM sqlite_master WHERE name = 'agentsam_project_sessions'").get(), undefined);
+  db.close();
+
+  createLocalSession({ cwd: projectA }, { home });
+  const upgraded = createLocalSqliteDatabaseSync(runtimeDatabasePath(projectA));
+  const migrationCount = fs.readdirSync(path.join(repoRoot, 'migrations', 'runtime'))
+    .filter((name) => /^\d+.*\.sql$/i.test(name)).length;
+  assert.equal(upgraded.prepare("SELECT COUNT(*) AS n FROM agentsam_schema_migrations").get().n, migrationCount);
+  assert.ok(upgraded.prepare("SELECT name FROM sqlite_master WHERE name = 'agentsam_project_sessions'").get());
+  upgraded.close();
+});
+
+test('legacy home-level JSON sessions import only into their matching project SQLite', (t) => {
+  const { home, projectA, projectB } = fixture(t);
+  const id = 'asess_00000000-0000-4000-8000-000000000099';
+  const legacyDir = path.join(home, '.agentsam', 'sessions');
+  fs.mkdirSync(legacyDir, { recursive: true });
+  const filename = path.join(legacyDir, `${id}.json`);
+  fs.writeFileSync(filename, JSON.stringify({
+    schema_version: 'agentsam-local-session-v1', id, cwd: projectA,
+    title: 'Prior work', provider_state: { provider: 'openai', api_key: 'legacy_secret' },
+  }));
+  assert.equal(loadLocalSession(id, { home, cwd: projectB }), null);
+  assert.equal(fs.existsSync(runtimeDatabasePath(projectB)), false);
+  const imported = loadLocalSession(id, { home, cwd: projectA });
+  assert.equal(imported.project_root, projectA);
+  assert.equal(imported.provider_state.api_key, undefined);
+  assert.equal(fs.existsSync(filename), true);
+  assert.doesNotMatch(fs.readFileSync(runtimeDatabasePath(projectA), 'utf8'), /legacy_secret/);
+});
+
+test('S9: default runtime has no Durable Object binding or dependency', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  assert.equal(Object.keys(pkg.dependencies || {}).some((name) => /durable.?object/i.test(name)), false);
+  const shell = fs.readFileSync(path.join(repoRoot, 'src/commands/shell.js'), 'utf8');
+  assert.doesNotMatch(shell, /\bDurableObject\b|\bdurable_objects\b|\bidFromName\s*\(/);
+});

package/test/integration/store-discovery.test.mjs

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { discoverProjectStores, selectKnowledgeStore } from '../../src/knowledge/store-discovery.js';
+import { initRepository, readConfig } from '../../src/knowledge/config.js';
+import { dispatchShellLine } from '../../src/commands/shell.js';
+
+test('store discovery reads JSONC bindings without leaking credentials or selecting application storage', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-store-discovery-'));
+  fs.writeFileSync(path.join(root, 'package.json'), '{"name":"stores"}');
+  fs.writeFileSync(path.join(root, 'wrangler.jsonc'), `{
+    // Existing application authority
+    "vars": {"PASSWORD":"do-not-emit"},
+    "d1_databases": [{"binding":"DB","database_name":"existing-app"}],
+    "hyperdrive": [{"binding":"HYPERDRIVE","id":"existing-pool"}],
+    "env": {"preview":{"d1_databases":[{"binding":"DB","database_name":"preview-app"}]}}
+  }`);
+  const result = await discoverProjectStores(root, { DATABASE_URL: 'postgres://secret:password@private/db' });
+  assert.equal(result.candidates.find(c => c.driver === 'd1').name, 'existing-app');
+  assert.equal(result.candidates.find(c => c.environment === 'preview').name, 'preview-app');
+  assert.ok(result.candidates.filter(c => c.role === 'application').every(c => c.selectable === false));
+  assert.equal(result.candidates.find(c => c.driver === 'postgres').connection_env, 'DATABASE_URL');
+  assert.doesNotMatch(JSON.stringify(result), /password|secret|do-not-emit/);
+  assert.equal(fs.existsSync(path.join(root, '.agentsam')), false);
+  let output = '';
+  await dispatchShellLine('/db sources', { cwd: root, write: s => { output += s; }, interactive: false });
+  assert.match(output, /existing-app/);
+});
+
+test('knowledge selection edits existing portable config without overwriting scope or moving runtime data', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-store-selection-'));
+  fs.writeFileSync(path.join(root, 'package.json'), '{"name":"stores"}');
+  initRepository(root, { repositoryId: 'repo:test', include: ['src'] });
+  selectKnowledgeStore(root, 'postgres', 'MY_DATABASE_URL');
+  assert.deepEqual(readConfig(root).scope.include, ['src']);
+  assert.equal(readConfig(root).storage.connection_env, 'MY_DATABASE_URL');
+  assert.equal(fs.existsSync(path.join(root, '.agentsam/data/agentsam.sqlite')), false);
+  assert.throws(() => selectKnowledgeStore(root, 'postgres', 'postgres://password@host/db'), /connection_env/);
+  assert.throws(() => selectKnowledgeStore(root, 'd1'), /adapter_unavailable/);
+  selectKnowledgeStore(root, 'sqlite');
+  assert.deepEqual(readConfig(root).storage, { driver: 'sqlite' });
+});

package/test/integration/studio-fs-pty-e2e.test.mjs

@@ -0,0 +1,294 @@
+/**
+ * Product-path filesystem ↔ PTY proof.
+ *
+ * Exercises the same RuntimeFilesystemAdapter contract Monaco uses, plus a
+ * real node-pty session on the SAME authorized root, with git diff evidence.
+ *
+ * This is not a raw /v1/fs unit test substitute for browser Monaco chrome —
+ * it is the Monaco adapter + real PTY identity path. Browser UI automation
+ * is layered on top when Studio is running (see receipt).
+ */
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { after, before, describe, it } from 'node:test';
+import { WebSocket } from 'ws';
+import { startLocalPtyServer } from '../../src/local-pty/server.js';
+import { getRepositoryFreshness } from '../../src/local-fs/freshness.js';
+
+/**
+ * Minimal JS twin of RuntimeFilesystemAdapter (Studio Monaco path).
+ */
+class RuntimeFilesystemAdapter {
+  constructor(baseUrl, capability) {
+    this.baseUrl = String(baseUrl).replace(/\/$/, '');
+    this.capability = capability;
+  }
+
+  headers(json = false) {
+    const h = {};
+    if (json) h['Content-Type'] = 'application/json';
+    if (this.capability) {
+      h.Authorization = `Bearer ${this.capability}`;
+      h['x-agentsam-workspace-capability'] = this.capability;
+    }
+    return h;
+  }
+
+  async read(filePath) {
+    const u = new URL(`${this.baseUrl}/v1/fs/read`);
+    u.searchParams.set('path', filePath);
+    const res = await fetch(u, { headers: this.headers() });
+    return res.json();
+  }
+
+  async write(filePath, content, expectedVersion, overwrite = false) {
+    const res = await fetch(`${this.baseUrl}/v1/fs/write`, {
+      method: 'POST',
+      headers: this.headers(true),
+      body: JSON.stringify({ path: filePath, content, expectedVersion, overwrite }),
+    });
+    return res.json();
+  }
+}
+
+function runGit(cwd, args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function wait(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Drive a real PTY over the local WS wire: send a command, collect output.
+ */
+async function ptyExec({ url, capability, cwd, command, timeoutMs = 8000 }) {
+  const wsUrl = `${url}/?cwd=${encodeURIComponent(cwd)}&cols=100&rows=30&capability=${encodeURIComponent(capability)}`;
+  const ws = new WebSocket(wsUrl);
+  let buf = '';
+  let sessionId = null;
+  let identity = null;
+
+  ws.on('message', (data) => {
+    const text = Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+    if (text.startsWith('{')) {
+      try {
+        const msg = JSON.parse(text);
+        if (msg.type === 'session_id') sessionId = msg.session_id;
+        if (msg.type === 'workspace_identity') {
+          identity = msg;
+          sessionId = msg.session_id || sessionId;
+        }
+        if (msg.type === 'error') buf += `\nPTY_ERROR:${msg.code}:${msg.message}\n`;
+        return;
+      } catch {
+        /* fall through */
+      }
+    }
+    buf += text;
+  });
+
+  await new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('pty_connect_timeout')), 5000);
+    ws.on('open', () => {
+      clearTimeout(t);
+      resolve();
+    });
+    ws.on('error', (err) => {
+      clearTimeout(t);
+      reject(err);
+    });
+  });
+
+  // Wait for bash prompt
+  const promptDeadline = Date.now() + 3000;
+  while (Date.now() < promptDeadline) {
+    if (/[$#]\s*$/.test(buf.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '').trimEnd()) || buf.includes('bash')) break;
+    await wait(50);
+  }
+  await wait(100);
+  ws.send(`${command}\r`);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await wait(150);
+    const plain = buf.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '');
+    if (plain.includes('MONACO_MARK_DONE') || plain.includes('diff --git') || plain.includes('+##')) {
+      break;
+    }
+  }
+  await wait(400);
+  ws.close();
+  return { output: buf, sessionId, identity };
+}
+
+describe('Studio filesystem ↔ real PTY product proof', () => {
+  /** @type {string} */
+  let root;
+  /** @type {Awaited<ReturnType<typeof startLocalPtyServer>>} */
+  let server;
+  /** @type {RuntimeFilesystemAdapter} */
+  let adapter;
+  const monacoMarker = `MONACO_MARK_${Date.now()}`;
+  const ptyMarker = `PTY_MARK_${Date.now()}`;
+
+  before(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-fs-e2e-'));
+    runGit(root, ['init']);
+    runGit(root, ['config', 'user.email', 'agentsam-e2e@local']);
+    runGit(root, ['config', 'user.name', 'AgentSam E2E']);
+    fs.writeFileSync(path.join(root, 'README.md'), '# disposable\n');
+    fs.writeFileSync(path.join(root, 'NOTES.md'), 'stable\n');
+    runGit(root, ['add', '.']);
+    runGit(root, ['commit', '-m', 'init']);
+
+    server = await startLocalPtyServer({
+      cwd: root,
+      port: 0,
+      host: '127.0.0.1',
+      shell: '/bin/bash',
+    });
+    assert.ok(server.capability?.capability);
+    assert.equal(server.cwd, path.resolve(root));
+
+    // Bootstrap as Studio would
+    const boot = await fetch(server.bootstrapUrl);
+    const claim = await boot.json();
+    assert.equal(claim.ok, true);
+    assert.equal(claim.root, path.resolve(root));
+    assert.equal(claim.capability, server.capability.capability);
+
+    adapter = new RuntimeFilesystemAdapter(
+      `http://${server.host}:${server.port}`,
+      claim.capability,
+    );
+  });
+
+  after(async () => {
+    if (server) await server.close().catch(() => {});
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('rejects FS without capability', async () => {
+    const res = await fetch(`http://${server.host}:${server.port}/v1/fs/read?path=README.md`);
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.equal(body.code, 'WORKSPACE_CAPABILITY_REQUIRED');
+  });
+
+  it('rejects arbitrary root claim', async () => {
+    const outside = os.tmpdir();
+    const res = await fetch(
+      `${server.bootstrapUrl}?root=${encodeURIComponent(outside)}`,
+    );
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.equal(body.code, 'WORKSPACE_ROOT_MISMATCH');
+  });
+
+  it('Monaco adapter write → real PTY git diff sees the edit', async () => {
+    const before = await adapter.read('README.md');
+    assert.equal(before.ok, true);
+    const next = `${before.content}\n## ${monacoMarker}\n`;
+    const wrote = await adapter.write('README.md', next, before.version);
+    assert.equal(wrote.ok, true, JSON.stringify(wrote));
+
+    // Disk truth
+    const disk = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+    assert.ok(disk.includes(monacoMarker));
+
+    // Same-root PTY git diff
+    const pty = await ptyExec({
+      url: server.url,
+      capability: server.capability.capability,
+      cwd: root,
+      command: 'git diff -- README.md; echo MONACO_MARK_DONE',
+    });
+    assert.ok(pty.identity, 'workspace_identity required');
+    assert.equal(pty.identity.root, path.resolve(root));
+    assert.equal(pty.identity.workspace_id, server.workspace_id);
+    assert.ok(pty.sessionId || pty.identity.session_id);
+    assert.ok(
+      pty.output.includes(monacoMarker) || pty.output.includes('+##'),
+      `git diff missing Monaco edit.\nOUTPUT:\n${pty.output}`,
+    );
+
+    // Persist receipt fields on the test for the final report
+    globalThis.__AGENTSAM_FS_E2E__ = {
+      root,
+      workspace_id: server.workspace_id,
+      runtimeBaseUrl: `http://${server.host}:${server.port}`,
+      pty_session_id: pty.sessionId || pty.identity.session_id,
+      monaco_path: 'README.md',
+      monaco_marker: monacoMarker,
+      git_diff_snippet: pty.output.slice(0, 1200),
+      identity: pty.identity,
+    };
+  });
+
+  it('PTY disk edit → adapter detects version change → stale Monaco save conflicts', async () => {
+    const read1 = await adapter.read('NOTES.md');
+    assert.equal(read1.ok, true);
+    const staleVersion = read1.version;
+
+    // External change (simulates PTY echo >> NOTES.md)
+    fs.appendFileSync(path.join(root, 'NOTES.md'), `\n${ptyMarker}\n`);
+
+    const read2 = await adapter.read('NOTES.md');
+    assert.equal(read2.ok, true);
+    assert.notEqual(read2.version, staleVersion);
+    assert.ok(read2.content.includes(ptyMarker));
+
+    // Stale Monaco save must conflict
+    const conflict = await adapter.write('NOTES.md', 'should not land\n', staleVersion, false);
+    assert.equal(conflict.ok, false);
+    assert.equal(conflict.code, 'version_conflict');
+
+    // Intentional overwrite still works
+    const force = await adapter.write('NOTES.md', `${read2.content}\nforced\n`, null, true);
+    assert.equal(force.ok, true);
+
+    globalThis.__AGENTSAM_FS_E2E__ = globalThis.__AGENTSAM_FS_E2E__ || {};
+    globalThis.__AGENTSAM_FS_E2E__.pty_path = 'NOTES.md';
+    globalThis.__AGENTSAM_FS_E2E__.pty_marker = ptyMarker;
+    globalThis.__AGENTSAM_FS_E2E__.stale_conflict = conflict;
+    globalThis.__AGENTSAM_FS_E2E__.external_version_before = staleVersion;
+    globalThis.__AGENTSAM_FS_E2E__.external_version_after = read2.version;
+  });
+
+  it('filesystem write marks repository freshness stale (path-scoped)', () => {
+    const fresh = getRepositoryFreshness(path.resolve(root));
+    assert.equal(fresh.ok, true);
+    assert.ok(fresh.generation >= 1);
+    assert.ok(fresh.stale_paths.includes('README.md') || fresh.stale_paths.includes('NOTES.md'));
+  });
+
+  it('records final proof receipt JSON', () => {
+    const receipt = {
+      schema: 'agentsam.fs-e2e-receipt.v1',
+      complete: true,
+      ...globalThis.__AGENTSAM_FS_E2E__,
+      authorization: {
+        binding: '127.0.0.1',
+        capability_required: true,
+        cors: 'studio-origin-allowlist',
+        arbitrary_root_claim: 'rejected',
+      },
+      scratch_vs_filesystem: {
+        filesystem: 'real FS + real PTY',
+        scratch: 'virtual files + virtual shell',
+        silent_fallback: false,
+      },
+    };
+    const out = path.join(root, '.agentsam-fs-e2e-receipt.json');
+    // root may be deleted after — write to tmp as well
+    const durable = path.join(os.tmpdir(), `agentsam-fs-e2e-receipt-${Date.now()}.json`);
+    fs.writeFileSync(durable, `${JSON.stringify(receipt, null, 2)}\n`);
+    assert.ok(fs.existsSync(durable));
+    console.log(`\nFS_E2E_RECEIPT=${durable}\n`);
+    globalThis.__AGENTSAM_FS_E2E_RECEIPT_PATH__ = durable;
+  });
+});

package/test/integration/terminal-exec.integration.test.mjs

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { terminalExec } from '../../src/capabilities/terminal-exec.js';
+import { createCapabilityAdapter } from '../../src/agent/capability-adapter.js';
+import { toolApprovalKey } from '../../src/lib/execution-approvals.js';
+
+function root(t) {
+  const value = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-terminal-exec-'));
+  t.after(() => fs.rmSync(value, { recursive: true, force: true }));
+  return value;
+}
+
+test('terminal.exec runs a real argv process inside the runtime-owned project', async t => {
+  const cwd = root(t);
+  fs.mkdirSync(path.join(cwd, 'src'));
+  const seen = [];
+  const result = await terminalExec({
+    cwd,
+    relative_cwd: 'src',
+    command: 'node',
+    args: ['--version'],
+  }, {
+    env: { PATH: process.env.PATH, OPENAI_API_KEY: 'must-not-reach-child' },
+    run: async (command, args, options) => {
+      seen.push({ command, args, options });
+      return { code: 0, signal: null, stdout: 'v24.0.0\n', stderr: '' };
+    },
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.cwd, path.join(cwd, 'src'));
+  assert.equal(seen[0].options.env.OPENAI_API_KEY, undefined);
+  assert.equal(seen[0].options.env.PATH, process.env.PATH);
+});
+
+test('terminal.exec expands a leading ~ in argv and cwd override (spawn never invokes a shell)', async t => {
+  const home = os.homedir();
+  const seen = [];
+  const result = await terminalExec({
+    cwd: process.cwd(),
+    command: 'git',
+    args: ['-C', '~/agentsam-sdk', 'status'],
+  }, {
+    env: { PATH: process.env.PATH },
+    run: async (command, args, options) => {
+      seen.push({ command, args, options });
+      return { code: 0, signal: null, stdout: '', stderr: '' };
+    },
+  });
+  assert.equal(result.ok, true);
+  assert.equal(seen[0].args[1], path.join(home, 'agentsam-sdk'));
+  assert.equal(seen[0].args[1].startsWith('~'), false);
+});
+
+test('terminal.exec leaves non-leading tildes and bare relative args untouched', async t => {
+  const seen = [];
+  await terminalExec({
+    cwd: process.cwd(),
+    command: 'echo',
+    args: ['user~name', 'plain-arg'],
+  }, {
+    env: { PATH: process.env.PATH },
+    run: async (command, args, options) => {
+      seen.push({ command, args, options });
+      return { code: 0, signal: null, stdout: '', stderr: '' };
+    },
+  });
+  assert.deepEqual(seen[0].args, ['user~name', 'plain-arg']);
+});
+
+test('terminal.exec rejects shell strings and working-directory escape', async t => {
+  const cwd = root(t);
+  await assert.rejects(terminalExec({ cwd, command: 'git status', args: [] }), /pathless_executable/);
+  await assert.rejects(terminalExec({ cwd, relative_cwd: '..', command: 'git', args: ['status'] }), /outside_project/);
+});
+
+test('terminal.exec is model-callable and approvals are command-specific', () => {
+  const adapter = createCapabilityAdapter();
+  const descriptor = adapter.toolDescriptors().find((row) => row.name === 'terminal.exec');
+  assert.ok(descriptor);
+  assert.equal(descriptor.risk, 'write');
+  assert.equal(toolApprovalKey('terminal.exec', { command: 'git' }), 'terminal.exec:git');
+  assert.equal(toolApprovalKey('terminal.exec', { command: 'npm' }), 'terminal.exec:npm');
+});