atris 3.15.56 → 3.16.0

package/commands/terminal.js

@@ -81,6 +81,18 @@ async function resolveBusiness(token, slug) {
   return null;
 }
 
+async function runTerminalCommand(token, businessId, workspaceId, command, timeoutSec = 30) {
+  return apiRequestJson(
+    `/business/${businessId}/workspaces/${workspaceId}/terminal`,
+    {
+      method: 'POST',
+      token,
+      body: { command, timeout: timeoutSec },
+      timeoutMs: (timeoutSec + 10) * 1000,
+    }
+  );
+}
+
 async function terminalAtris() {
   // Parse args. Three forms:
   //   atris terminal <business> <command...>
@@ -162,15 +174,7 @@ async function terminalAtris() {
   }
 
   // Execute the command
-  const result = await apiRequestJson(
-    `/business/${biz.businessId}/workspaces/${biz.workspaceId}/terminal`,
-    {
-      method: 'POST',
-      token: creds.token,
-      body: { command, timeout: timeoutSec },
-      timeoutMs: (timeoutSec + 10) * 1000,
-    }
-  );
+  const result = await runTerminalCommand(creds.token, biz.businessId, biz.workspaceId, command, timeoutSec);
 
   if (!result.ok) {
     console.error(`\n✗ Terminal call failed: ${result.errorMessage || result.error || result.status}`);
@@ -198,4 +202,4 @@ async function terminalAtris() {
   process.exit(typeof exitCode === 'number' ? exitCode : 0);
 }
 
-module.exports = { terminalAtris };
+module.exports = { terminalAtris, resolveBusiness, ensureAwake, runTerminalCommand };

package/commands/wiki.js

@@ -192,7 +192,7 @@ function printWikiHelp(scope = null) {
     console.log('');
     console.log('Build a local or cloud wiki lint prompt.');
   } else {
-    console.log('Usage: atris wiki <ingest|query|lint|search|log|loop|verify> [business] [args]');
+    console.log('Usage: atris wiki <ingest|query|lint|search|log|loop|verify|entities|related> [business] [args]');
     console.log('');
     console.log('  ingest <path>                 Local-first ingest into atris/wiki/');
     console.log('  query  "question"             Local-first query against atris/wiki/');
@@ -201,6 +201,8 @@ function printWikiHelp(scope = null) {
     console.log('  log    [business] [N]         Show recent atris/wiki/log.md entries');
     console.log('  loop                          Run local wiki upkeep analysis and refresh STATUS/log');
     console.log('  verify                        Check agent-readable source/verification metadata');
+    console.log('  entities [--type T] [--json]  List extracted graph entities');
+    console.log('  related <entity> [--json]     List graph relationships touching entity');
   }
   console.log('');
   console.log('Flags:');
@@ -213,6 +215,80 @@ function printWikiHelp(scope = null) {
   console.log('');
 }
 
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+function optionValue(args, name, fallback = null) {
+  const index = args.indexOf(name);
+  if (index === -1 || index + 1 >= args.length) return fallback;
+  return args[index + 1];
+}
+
+function printJsonOrText(payload, lines, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  lines.forEach((line) => console.log(line));
+}
+
+function readWikiGraph(root = process.cwd()) {
+  const graphPath = path.join(root, 'atris', 'wiki', '.graph.json');
+  if (!fs.existsSync(graphPath)) {
+    return { graphPath, graph: { schema: 'atris.wiki_graph.v1', entities: [], relationships: [] } };
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+    return {
+      graphPath,
+      graph: {
+        schema: parsed.schema || 'atris.wiki_graph.v1',
+        updated_at: parsed.updated_at || null,
+        entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+        relationships: Array.isArray(parsed.relationships) ? parsed.relationships : [],
+      },
+    };
+  } catch {
+    return { graphPath, graph: { schema: 'atris.wiki_graph.v1', entities: [], relationships: [] } };
+  }
+}
+
+function wikiEntities(args = []) {
+  const asJson = hasFlag(args, '--json');
+  const type = optionValue(args, '--type', null);
+  const { graphPath, graph } = readWikiGraph();
+  const entities = type ? graph.entities.filter((entity) => entity.type === type) : graph.entities;
+  printJsonOrText(
+    { ok: true, action: 'entities', graph_path: graphPath, type: type || null, entities },
+    entities.length
+      ? entities.map((entity) => `${entity.type || 'concept'}\t${entity.name}`)
+      : ['No wiki graph entities found. Run: atris member wake wiki-miner --execute'],
+    asJson,
+  );
+}
+
+function wikiRelated(args = []) {
+  const asJson = hasFlag(args, '--json');
+  const entity = args.filter((arg) => arg !== '--json')[0] || '';
+  if (!entity) {
+    console.error('Usage: atris wiki related <entity>');
+    process.exit(1);
+  }
+  const wanted = entity.toLowerCase();
+  const { graphPath, graph } = readWikiGraph();
+  const related = graph.relationships
+    .filter((relationship) => String(relationship.from || '').toLowerCase() === wanted || String(relationship.to || '').toLowerCase() === wanted)
+    .slice(0, 5);
+  printJsonOrText(
+    { ok: true, action: 'related', graph_path: graphPath, entity, relationships: related },
+    related.length
+      ? related.map((relationship) => `${relationship.from} -[${relationship.type}]-> ${relationship.to}`)
+      : [`No wiki graph relationships found for "${entity}".`],
+    asJson,
+  );
+}
+
 async function wikiIngest(mode, slug, sourceValue) {
   if (!sourceValue) {
     console.error('Usage: atris wiki ingest [business] <path>');
@@ -414,6 +490,14 @@ async function wikiCommand(subcommand, ...args) {
   const { mode, args: cleanArgs } = parseModeArgs(args);
 
   switch (subcommand) {
+    case 'entities': {
+      wikiEntities(cleanArgs);
+      break;
+    }
+    case 'related': {
+      wikiRelated(cleanArgs);
+      break;
+    }
     case 'ingest': {
       const [slug, sourceValue] = mode === 'cloud' ? parseCloudArgs(cleanArgs) : [null, cleanArgs.join(' ')];
       await wikiIngest(mode, slug, sourceValue);
@@ -494,4 +578,6 @@ module.exports = {
   wikiSearch,
   wikiLog,
   wikiVerify,
+  wikiEntities,
+  wikiRelated,
 };

package/commands/workflow.js

@@ -63,101 +63,294 @@ function confidenceGatePrompt(stage) {
   ].join('\n');
 }
 
-function printAtris2Result(response) {
-  if (!response || !Array.isArray(response.result)) {
-    console.log(JSON.stringify(response, null, 2));
-    return;
+// Translate one relayed local_file_op call into a single bash command that runs
+// on the business cloud workspace, mirroring the backend handler's result shapes.
+// Content for write/edit travels base64 so shell quoting can't corrupt it.
+function cloudFileOpCommand(args) {
+  const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+  const b64 = (s) => Buffer.from(String(s), 'utf8').toString('base64');
+  const op = String(args.type || '').toLowerCase();
+  const rawPath = String(args.path || '.');
+  if (rawPath.split('/').includes('..')) return null;
+  const p = q(rawPath);
+
+  if (op === 'bash') return `cd /workspace && ( ${args.command || 'true'} )`;
+  if (op === 'list') return `cd /workspace && find ${p} -maxdepth 3 -not -path '*/node_modules/*' -not -path '*/.git/*' | head -200`;
+  if (op === 'search') {
+    const query = q(String(args.query || args.pattern || ''));
+    return `cd /workspace && grep -rn -m 50 ${query} ${p} 2>/dev/null | head -50`;
+  }
+  if (op === 'read') return `cd /workspace && { [ -d ${p} ] && ls -p ${p} | head -200 || head -c 12000 ${p}; }`;
+  if (op === 'write') {
+    return `cd /workspace && mkdir -p "$(dirname ${p})" && echo ${q(b64(args.content || ''))} | base64 -d > ${p} && echo WROTE ${p}`;
+  }
+  if (op === 'edit') {
+    const py = [
+      'import base64,sys',
+      `p=base64.b64decode('${b64(rawPath)}').decode()`,
+      `f=base64.b64decode('${b64(args.find || '')}').decode()`,
+      `r=base64.b64decode('${b64(args.replace || '')}').decode()`,
+      's=open(p).read()',
+      "sys.exit('find text not found') if f not in s else open(p,'w').write(s.replace(f,r,1))",
+    ].join('; ');
+    return `cd /workspace && python3 -c ${q(py)} && echo EDITED ${p}`;
+  }
+  return null;
+}
+
+function cloudFileOpResult(args, term) {
+  const op = String(args.type || '').toLowerCase();
+  const body = (term && term.data) || {};
+  const stdout = body.stdout || '';
+  const stderr = body.stderr || '';
+  const exitCode = body.exit_code !== undefined ? body.exit_code : null;
+  if (!term.ok) {
+    return { status: 'error', error: term.errorMessage || term.error || `terminal HTTP ${term.status}` };
+  }
+  if (exitCode !== 0 && exitCode !== null) {
+    return { status: 'error', error: (stderr || stdout || 'command failed').slice(0, 2000), exit_code: exitCode };
   }
+  if (op === 'bash') return { status: 'ok', stdout, stderr, exit_code: exitCode };
+  if (op === 'read') return { status: 'ok', path: args.path || '.', content: stdout.slice(0, 12000) };
+  if (op === 'write' || op === 'edit') return { status: 'ok', path: args.path };
+  return { status: 'ok', stdout: stdout.slice(0, 12000) };
+}
+
+function makeCloudExecutor({ token, businessId, workspaceId, slug }) {
+  const { runTerminalCommand } = require('./terminal');
+  return async function executeToolCall(name, args) {
+    if (name !== 'local_file_op') {
+      return { status: 'error', error: `unsupported relayed tool: ${name}` };
+    }
+    const command = cloudFileOpCommand(args || {});
+    if (!command) {
+      return { status: 'error', error: `unsupported op or unsafe path on cloud workspace ${slug}` };
+    }
+    try {
+      const term = await runTerminalCommand(token, businessId, workspaceId, command, 60);
+      return cloudFileOpResult(args || {}, term);
+    } catch (err) {
+      return { status: 'error', error: String(err.message || err).slice(0, 500) };
+    }
+  };
+}
+
+function postToolResult(callId, result, base = 'http://127.0.0.1:8000') {
+  const url = new URL('/api/atris2/turn/tool-result', base);
+  const transport = url.protocol === 'https:' ? require('https') : require('http');
+  return new Promise((resolve, reject) => {
+    const postData = JSON.stringify({ call_id: callId, result });
+    const req = transport.request({
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+        Origin: 'http://localhost:8000'
+      }
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => data += c);
+      res.on('end', () => res.statusCode === 200 ? resolve() : reject(new Error(`tool-result HTTP ${res.statusCode}: ${data.slice(0, 200)}`)));
+    });
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
+}
+
+function atris2TurnRequest(payload, executeToolCall = null) {
+  const http = require('http');
+  return new Promise((resolve, reject) => {
+    const postData = JSON.stringify(payload);
+    const req = http.request({
+      hostname: '127.0.0.1',
+      port: 8000,
+      path: '/api/atris2/turn',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+        // Local-desktop auth: the backend treats localhost requests with a
+        // localhost Origin as the free local-desktop user.
+        Origin: 'http://localhost:8000'
+      }
+    }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        let data = '';
+        res.on('data', (chunk) => data += chunk);
+        res.on('end', () => {
+          let detail = data;
+          try { detail = JSON.parse(data).detail || data; } catch (e) { /* raw body */ }
+          const err = new Error(`HTTP ${res.statusCode}: ${detail}`.slice(0, 400));
+          err.statusCode = res.statusCode;
+          reject(err);
+        });
+        return;
+      }
 
-  let wroteText = false;
-  for (const event of response.result) {
-    if (event && event.type === 'text' && event.content) {
-      process.stdout.write(event.content);
-      wroteText = true;
-    } else if (event && event.type === 'assistant' && Array.isArray(event.content)) {
-      for (const block of event.content) {
-        if (block && block.type === 'text' && block.text) {
-          process.stdout.write(block.text);
+      // SSE stream: print text deltas live, surface tool calls, capture result.
+      let buffer = '';
+      let finalResult = null;
+      let streamError = null;
+      let wroteText = false;
+      let idleTimer = null;
+      const IDLE_MS = 120000;
+      const resetIdle = () => {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          req.destroy();
+          reject(new Error(`Stream stalled: no events for ${IDLE_MS / 1000}s`));
+        }, IDLE_MS);
+      };
+      resetIdle();
+
+      // Relayed tool calls run sequentially: the backend awaits each result
+      // before continuing the loop, so a promise chain preserves order.
+      let toolChain = Promise.resolve();
+      const handleEvent = (event) => {
+        if (!event || typeof event !== 'object') return;
+        if (event.type === 'text_delta' && event.content) {
+          process.stdout.write(event.content);
           wroteText = true;
+        } else if (event.type === 'tool_call_request' && executeToolCall) {
+          const { call_id: callId, name, args } = event;
+          const label = (args && args.type) || name || 'tool';
+          console.log(`\n⚙ cloud:${label}${args && args.command ? ` $ ${String(args.command).slice(0, 80)}` : ''}${args && args.path ? ` ${args.path}` : ''}`);
+          toolChain = toolChain
+            .then(() => executeToolCall(name, args))
+            .catch((err) => ({ status: 'error', error: String(err.message || err).slice(0, 500) }))
+            .then((result) => postToolResult(callId, result))
+            .then(() => resetIdle())
+            .catch((err) => console.error(`✗ tool relay failed: ${err.message}`));
+        } else if (event.type === 'tool_call') {
+          const name = event.tool || (event.input && event.input.tool) || 'tool';
+          console.log(`\n⚙ ${name}...`);
+        } else if (event.type === 'error') {
+          streamError = event.error || 'Atris 2 returned an error.';
+        } else if (event.type === 'result' && typeof event.result === 'string') {
+          finalResult = event.result;
         }
-      }
-    }
-  }
+      };
 
-  if (wroteText) {
-    console.log('');
-  } else {
-    console.log(JSON.stringify(response.result, null, 2));
-  }
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        resetIdle();
+        buffer += chunk;
+        let idx;
+        while ((idx = buffer.indexOf('\n\n')) !== -1) {
+          const frame = buffer.slice(0, idx);
+          buffer = buffer.slice(idx + 2);
+          for (const line of frame.split('\n')) {
+            if (!line.startsWith('data: ')) continue;
+            try {
+              handleEvent(JSON.parse(line.slice(6)));
+            } catch (e) { /* ignore malformed frame */ }
+          }
+        }
+      });
+      res.on('end', () => {
+        if (idleTimer) clearTimeout(idleTimer);
+        if (streamError) {
+          reject(new Error(streamError));
+          return;
+        }
+        resolve({ finalResult, wroteText });
+      });
+      res.on('error', (err) => {
+        if (idleTimer) clearTimeout(idleTimer);
+        reject(err);
+      });
+    });
+
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
 }
 
 async function runAtris2Local(userInput, atris2Mode) {
-  console.log(`🚀 EXECUTING VIA ATRIS 2 ${atris2Mode.toUpperCase()}`);
+  let actualCommand = String(userInput || '').trim().replace(/^2\s+(fast|pro)\b/i, '').trim();
+
+  // --business <slug>: run the turn against that business's cloud workspace.
+  // The model loop stays on the backend; every file/bash tool call is relayed
+  // here and executed on the business EC2 via the /terminal endpoint.
+  let businessSlug = null;
+  const bizMatch = actualCommand.match(/(?:^|\s)--business[= ]([a-z0-9-]+)/i);
+  if (bizMatch) {
+    businessSlug = bizMatch[1].toLowerCase();
+    actualCommand = actualCommand.replace(bizMatch[0], ' ').replace(/\s+/g, ' ').trim();
+  }
+
+  console.log(`🚀 EXECUTING VIA ATRIS 2 ${atris2Mode.toUpperCase()}${businessSlug ? ` → cloud workspace ${businessSlug}` : ''}`);
   console.log('');
 
-  const actualCommand = String(userInput || '').trim().replace(/^2\s+(fast|pro)\b/i, '').trim();
   if (!actualCommand) {
     console.log(`⚠ No command provided after "2 ${atris2Mode}"`);
-    console.log(`Usage: atris 2 ${atris2Mode} <your command>`);
+    console.log(`Usage: atris 2 ${atris2Mode} [--business <slug>] <your command>`);
     process.exit(1);
   }
 
   console.log(`Running: ${actualCommand}`);
   console.log('');
 
-  try {
-    const http = require('http');
-    const response = await new Promise((resolve, reject) => {
-      const postData = JSON.stringify({
-        message: actualCommand,
-        workspace_path: process.cwd(),
-        model: `atris-2-${atris2Mode}`
-      });
-
-      const options = {
-        hostname: '127.0.0.1',
-        port: 8000,
-        path: '/api/agent-sdk/fast',
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Content-Length': Buffer.byteLength(postData)
-        }
-      };
-
-      const req = http.request(options, (res) => {
-        let data = '';
-        res.on('data', (chunk) => data += chunk);
-        res.on('end', () => {
-          try {
-            const parsed = JSON.parse(data);
-            if (res.statusCode < 200 || res.statusCode >= 300) {
-              reject(new Error(parsed.detail || parsed.error || `HTTP ${res.statusCode}`));
-              return;
-            }
-            resolve(parsed);
-          } catch (e) {
-            reject(new Error(`Failed to parse response: ${data}`));
-          }
-        });
-      });
-
-      req.on('error', reject);
-      const timeoutMs = atris2Mode === 'pro' ? 30000 : 10000;
-      req.setTimeout(timeoutMs, () => {
-        req.destroy();
-        reject(new Error(`Request timeout after ${timeoutMs / 1000}s`));
-      });
-      req.write(postData);
-      req.end();
+  let executeToolCall = null;
+  const payload = {
+    message: actualCommand,
+    workspace_path: process.cwd(),
+    model: `atris:${atris2Mode}`
+  };
+
+  if (businessSlug) {
+    const { loadCredentials } = require('../utils/auth');
+    const { resolveBusiness, ensureAwake } = require('./terminal');
+    const creds = loadCredentials();
+    if (!creds || !creds.token) {
+      console.error('Not logged in. Run: atris login');
+      process.exit(1);
+    }
+    const biz = await resolveBusiness(creds.token, businessSlug);
+    if (!biz || !biz.workspaceId) {
+      console.error(`Business "${businessSlug}" not found or has no workspace.`);
+      process.exit(1);
+    }
+    const awake = await ensureAwake(creds.token, biz.businessId);
+    if (!awake) {
+      console.error('Cloud computer did not become ready in time.');
+      process.exit(1);
+    }
+    executeToolCall = makeCloudExecutor({
+      token: creds.token,
+      businessId: biz.businessId,
+      workspaceId: biz.workspaceId,
+      slug: businessSlug,
     });
+    payload.local_executor = true;
+    payload.workspace_path = `/workspace/${businessSlug}`;
+  }
 
-    if (response.error) {
-      throw new Error(response.error);
+  try {
+    let outcome;
+    try {
+      outcome = await atris2TurnRequest(payload, executeToolCall);
+    } catch (error) {
+      // Backends without local workspace access (prod config) reject the path;
+      // retry the same prompt as plain cloud chat. Never silently downgrade a
+      // cloud-workspace run.
+      if (!businessSlug && error.statusCode === 403 && /workspace/i.test(error.message)) {
+        outcome = await atris2TurnRequest({ ...payload, workspace_path: null });
+      } else {
+        throw error;
+      }
     }
 
+    if (!outcome.wroteText && outcome.finalResult) {
+      process.stdout.write(outcome.finalResult);
+    }
+    console.log('');
     console.log(`✅ Atris 2 ${atris2Mode} completed`);
-    printAtris2Result(response);
   } catch (error) {
     console.error(`✗ Error: ${error.message}`);
     console.error(`Atris 2 ${atris2Mode} failed before completion.`);
@@ -868,6 +1061,26 @@ async function reviewAtris() {
   const args = process.argv.slice(3);
   const executeFlag = args.includes('--execute');
   const showFull = args.includes('--full') || args.includes('--verbose');
+  const wantsTaskJson = args.includes('--json');
+
+  if (!executeFlag && !showFull) {
+    const forwarded = ['reviews', ...args.filter(arg => !['--execute', '--full', '--verbose'].includes(arg))];
+    const { run: runTaskCommand } = require('./task');
+    if (!wantsTaskJson) {
+      printWorkflowBrief([
+        'Atris Review is the human checkpoint for proof-ready work.',
+        'Accept only when the proof is real; revise when the claim is vague, stale, or too narrow.',
+        'Agents can add review proof here, but XP waits for human accept.',
+      ]);
+    }
+    await runTaskCommand(forwarded);
+    if (!wantsTaskJson) {
+      printWorkflowBrief([
+        'Need the legacy Validator prompt? Run `atris review --verbose`.',
+      ]);
+    }
+    return;
+  }
 
   const config = loadConfig();
   const executionMode = executeFlag ? 'agent' : (config.execution_mode || 'prompt');
@@ -1423,5 +1636,7 @@ module.exports = {
   planAtris,
   doAtris,
   reviewAtris,
-  executeAgentSDKFast
+  executeAgentSDKFast,
+  makeCloudExecutor,
+  postToolResult
 };

package/commands/worktree.js

@@ -209,6 +209,40 @@ function printStatus() {
   }
 }
 
+// Programmatic core shared by `atris worktree start` and `atris mission start
+// --worktree`: creates the branch + isolated checkout + identity sidecar and
+// returns the facts. Throws on failure; callers own messaging and next steps.
+function createAgentWorktree({ root = repoRoot(), member = '', agent = '', task, branch: branchOverride, path: pathOverride, base: baseOverride, now = new Date() } = {}) {
+  const owner = member || agent;
+  if (!owner || !task) throw new Error('createAgentWorktree: owner (member/agent) and task required');
+  const branch = branchOverride || branchName(owner, task, now);
+  const target = path.resolve(pathOverride || defaultWorktreePath(root, owner, task, now));
+  const base = normalizeTargetRef(root, baseOverride || defaultStartBase(root));
+  if (fs.existsSync(target)) throw new Error(`worktree path already exists: ${target}`);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  refreshRemoteRef(root, base);
+  runGit(['worktree', 'add', '-b', branch, target, base], { cwd: root });
+  runGit(['config', `branch.${branch}.atris-base`, base], { cwd: target, check: false });
+  runGit(['config', `branch.${branch}.atris-owner`, owner], { cwd: target, check: false });
+  runGit(['config', `branch.${branch}.atris-task`, task], { cwd: target, check: false });
+  fs.mkdirSync(path.join(target, '.atris'), { recursive: true });
+  fs.writeFileSync(
+    path.join(target, '.atris', 'agent-worktree.json'),
+    JSON.stringify({
+      agent: agent || null,
+      member: member || null,
+      owner,
+      task,
+      branch,
+      base,
+      workspace_root: root,
+      created_at: now.toISOString(),
+    }, null, 2) + '\n',
+    'utf8'
+  );
+  return { path: target, branch, base, owner };
+}
+
 function startWorktree(args) {
   const root = repoRoot();
   const member = readFlag(args, '--member');
@@ -219,25 +253,26 @@ function startWorktree(args) {
     console.error('Usage: atris worktree start --member <member>|--agent <name> --task "<short task>" [--claim]');
     return 2;
   }
-  const now = new Date();
-  const branch = readFlag(args, '--branch') || branchName(owner, task, now);
-  const target = path.resolve(readFlag(args, '--path') || defaultWorktreePath(root, owner, task, now));
-  const base = normalizeTargetRef(root, readFlag(args, '--base') || readFlag(args, '--target') || defaultStartBase(root));
   const memberFile = member ? path.join(root, 'atris', 'team', member, 'MEMBER.md') : '';
-
-  if (fs.existsSync(target)) {
-    console.error(`refusing: worktree path already exists: ${target}`);
-    return 2;
-  }
   if (memberFile && !fs.existsSync(memberFile)) {
     console.error(`warning: no member persona at ${path.relative(root, memberFile)}`);
   }
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  refreshRemoteRef(root, base);
-  runGit(['worktree', 'add', '-b', branch, target, base], { cwd: root });
-  runGit(['config', `branch.${branch}.atris-base`, base], { cwd: target, check: false });
-  runGit(['config', `branch.${branch}.atris-owner`, owner], { cwd: target, check: false });
-  runGit(['config', `branch.${branch}.atris-task`, task], { cwd: target, check: false });
+  let created;
+  try {
+    created = createAgentWorktree({
+      root,
+      member,
+      agent,
+      task,
+      branch: readFlag(args, '--branch'),
+      path: readFlag(args, '--path'),
+      base: readFlag(args, '--base') || readFlag(args, '--target'),
+    });
+  } catch (e) {
+    console.error(`refusing: ${e.message}`);
+    return 2;
+  }
+  const { path: target, branch, base } = created;
 
   const counts = statusCounts(root);
   if (counts && (counts.staged || counts.unstaged || counts.untracked)) {
@@ -474,9 +509,11 @@ function worktreeCommand(args = []) {
 
 module.exports = {
   branchName,
+  createAgentWorktree,
   defaultShipTarget,
   defaultStartBase,
   defaultWorktreePath,
+  listWorktrees,
   parseWorktrees,
   normalizeTargetRef,
   prMergeRef,