atris 3.34.0 → 3.36.0

package/ax

@@ -8,8 +8,11 @@ const path = require('path');
 const readline = require('readline');
 const crypto = require('crypto');
 const { Readable } = require('stream');
+const permissionGrants = require(path.join(__dirname, 'lib', 'permission-grants.js'));
 const { loadCredentials } = require('./utils/auth');
+const { apiRequestJson, getApiBaseUrl } = require('./utils/api');
 const missionRuntime = require('./lib/mission-runtime-loop');
+const { pickLane } = require('./lib/ax-auto-lane');
 
 const EXIT_WORDS = new Set(['exit', 'quit', ':q']);
 const BACKEND = {
@@ -29,7 +32,12 @@ const CONNECTION_CAPABILITIES_PATH = '/api/atris2/connection-capabilities';
 const ATRIS2_CONNECTION_STATUS_PATH = '/api/atris2/connection-status';
 const ATRIS2_HEALTH_PATH = '/api/atris2/health';
 const APPROVAL_EXECUTE_PATH = '/api/atris2/approvals/execute';
+const BACKEND_API_TOOL_NAME = 'backend_api';
+const BACKEND_API_TOOL_RESULT_PATH = '/api/atris2/turn/tool-result';
 const DEFAULT_APPROVAL_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TURN_TIMEOUT_MS = 60000;
+const PRO_TURN_TIMEOUT_MS = 180000;
+const MAX_TURN_TIMEOUT_MS = 300000;
 const CONNECTOR_NAMES = {
   gmail: 'Gmail',
   google_calendar: 'Google Calendar',
@@ -71,6 +79,18 @@ const ANSI = {
 
 const TIER_COLORS = { fast: '\x1b[32m', pro: '\x1b[36m', max: '\x1b[35m' };
 
+// Extend backend_api by adding one row here. Keep mutating endpoints narrow;
+// any non-get method is approval-gated before the HTTP request is made.
+const BACKEND_API_ALLOWLIST = [
+  { method: 'GET', endpoint: '/api/atris2/health', description: 'Atris2 health' },
+  { method: 'GET', endpoint: '/api/atris2/connection-status', description: 'connection status' },
+  { method: 'GET', endpoint: '/api/atris2/connection-capabilities', description: 'connection capabilities' },
+  { method: 'GET', endpoint: '/api/integrations/status', description: 'integration status' },
+  { method: 'GET', endpoint: '/api/ai-computer/user/status', description: 'personal computer status' },
+  { method: 'GET', endpoint: '/api/business', description: 'business list' },
+  { method: 'POST', endpoint: '/api/improve', description: 'run one improve tick' },
+];
+
 function tierColor(mode) {
   return TIER_COLORS[mode] || ANSI.accent;
 }
@@ -81,6 +101,33 @@ function modelForMode(mode) {
   return mode === 'fast' ? 'atris:fast' : 'atris:pro';
 }
 
+function payloadCanRunTools(payload = {}, options = {}) {
+  return Boolean(
+    options.business
+    || options.local
+    || payload.local_executor
+    || (Array.isArray(payload.local_tools) && payload.local_tools.length > 0)
+  );
+}
+
+function postTurnTimeoutMs(payload = {}, options = {}) {
+  const model = String(payload.model || '');
+  let timeoutMs = DEFAULT_TURN_TIMEOUT_MS;
+  if (model === 'atris:max') timeoutMs = MAX_TURN_TIMEOUT_MS;
+  else if (model === 'atris:pro') timeoutMs = PRO_TURN_TIMEOUT_MS;
+
+  // AX postTurn is the tool-capable Atris2 path. Fast tool turns need the same
+  // headroom as pro because the backend can spend long stretches inside tools
+  // without SSE traffic. Plain tool-free one-shot fast chat stays at 60s.
+  if (model === 'atris:fast' && payloadCanRunTools(payload, options)) {
+    timeoutMs = Math.max(timeoutMs, PRO_TURN_TIMEOUT_MS);
+  }
+  if (options.business || options.local) {
+    timeoutMs = Math.max(timeoutMs, PRO_TURN_TIMEOUT_MS);
+  }
+  return timeoutMs;
+}
+
 function formatDuration(ms) {
   const value = Number(ms) || 0;
   if (value < 1000) return `${Math.max(0, Math.round(value))}ms`;
@@ -115,23 +162,30 @@ function formatUsage() {
     'ax - Atris local/code agent',
     '',
     'Usage:',
-    '  ax [--max|--pro|--fast|--code-fast] [--local|--cloud] <message>',
-    '  ax [--max|--pro|--fast|--code-fast] [--local|--cloud] --chat',
+    '  ax [--auto|--max|--pro|--fast|--code-fast] [--local|--cloud] <message>',
+    '  ax [--auto|--max|--pro|--fast|--code-fast] [--local|--cloud] --print <message>',
+    '  ax [--auto|--max|--pro|--fast|--code-fast] [--local|--cloud] --chat',
     '  ax [--max|--pro|--fast] --business <slug> [<message>|--chat]',
     '  ax [--max|--pro|--fast|--code-fast] --doctor',
     '  ax --approvals',
     '  ax --approve <approval-id>',
     '  ax --deny <approval-id>',
+    '  ax --grant <approval-id>      approve and remember this exact command (this workspace)',
+    '  ax --grants                   list active permission grants',
+    '  ax --sync-grants              push/pull grants with atrisos-web',
+    '  ax --revoke-grant <grant-id>',
     '  ax --self-test',
     '  ax [--max|--fast] --benchmark',
     '',
     'Modes:',
+    '  --auto  pick a lane for each message and say why',
     '  --max   hosted Atris 2, highest reasoning, slowest turns',
     '  --pro   hosted Atris 2, deeper tool loop',
     '  --fast  hosted Atris 2, faster low-latency turns',
     '  --code-fast  Atris Code Fast public lane',
     '  --local opt into local backend/workspace tools',
     '  --cloud force authenticated cloud connectors/chat',
+    '  --print  headless JSON result, including auto_lane and auto_reason with --auto',
     '  --business <slug>  run tools on that business cloud workspace (EC2)',
     '  --verify <cmd>  gate the turn on this command passing (default: no verifier)',
     '',
@@ -177,10 +231,29 @@ function createRunLogger({ cwd = process.cwd(), mode = 'pro', kind = 'play', out
   ].join('\n'));
 
   let redactedChars = 0;
+  let logBuffer = '';
+  let logFlushTimer = null;
+  const flushLogBuffer = () => {
+    if (logFlushTimer) {
+      clearTimeout(logFlushTimer);
+      logFlushTimer = null;
+    }
+    if (!logBuffer) return;
+    fs.appendFileSync(logPath, logBuffer);
+    logBuffer = '';
+  };
+  const scheduleLogFlush = () => {
+    if (logFlushTimer) return;
+    logFlushTimer = setTimeout(() => {
+      logFlushTimer = null;
+      flushLogBuffer();
+    }, 500);
+  };
   const writeLog = (chunk) => {
     const text = stripAnsi(chunk);
     if (fullTranscript) {
-      fs.appendFileSync(logPath, text);
+      logBuffer += text;
+      scheduleLogFlush();
       return;
     }
     redactedChars += text.length;
@@ -200,6 +273,7 @@ function createRunLogger({ cwd = process.cwd(), mode = 'pro', kind = 'play', out
     output: teeOutput,
     write: writeLog,
     close(exitCode = 0) {
+      flushLogBuffer();
       if (!fullTranscript) {
         fs.appendFileSync(logPath, `redacted_chars: ${redactedChars}\n`);
         fs.appendFileSync(logPath, 'note: full transcript disabled by default; set AX_LOG_FULL=1 to opt in.\n');
@@ -207,6 +281,7 @@ function createRunLogger({ cwd = process.cwd(), mode = 'pro', kind = 'play', out
         return;
       }
       writeLog(`\nexit_code: ${exitCode}\nfinished_at: ${new Date().toISOString()}\n`);
+      flushLogBuffer();
     }
   };
 }
@@ -495,6 +570,201 @@ function postJson(pathname, body, { token = authToken(), timeoutMs = 30000, rout
   });
 }
 
+function compactSingleLine(value) {
+  return String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
+}
+
+function truncateSingleLine(value, limit = 120) {
+  const text = compactSingleLine(value);
+  if (text.length <= limit) return text;
+  if (limit <= 3) return text.slice(0, limit);
+  return `${text.slice(0, limit - 3)}...`;
+}
+
+function canonicalBackendApiPath(pathname) {
+  let value = String(pathname || '').trim();
+  if (!value) return '';
+  if (!value.startsWith('/')) value = `/${value}`;
+  value = value.replace(/\/{2,}/g, '/');
+  if (value !== '/' && value.endsWith('/')) value = value.replace(/\/+$/, '');
+  return value;
+}
+
+function normalizeBackendApiMethod(method) {
+  return String(method || 'GET').trim().toUpperCase() || 'GET';
+}
+
+function normalizeBackendApiEndpoint(endpoint) {
+  const raw = String(endpoint || '').trim();
+  if (!raw || /^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) return null;
+  const parsed = new URL(raw.startsWith('/') ? raw : `/${raw}`, 'https://ax.local');
+  const pathOnly = canonicalBackendApiPath(parsed.pathname);
+  const displayPath = pathOnly === '/api' || pathOnly.startsWith('/api/')
+    ? pathOnly
+    : canonicalBackendApiPath(`/api${pathOnly}`);
+  return {
+    endpoint: `${displayPath}${parsed.search}`,
+    pathname: displayPath,
+    search: parsed.search,
+  };
+}
+
+function backendApiAllowlistEntry(method, endpointPathname) {
+  const normalizedMethod = normalizeBackendApiMethod(method);
+  const normalizedPath = canonicalBackendApiPath(endpointPathname);
+  return BACKEND_API_ALLOWLIST.find(row =>
+    row.method === normalizedMethod && canonicalBackendApiPath(row.endpoint) === normalizedPath
+  ) || null;
+}
+
+function apiRequestPathForBackendEndpoint(displayEndpoint, baseUrl = getApiBaseUrl()) {
+  const parsed = new URL(displayEndpoint, 'https://ax.local');
+  let pathname = canonicalBackendApiPath(parsed.pathname);
+  const base = String(baseUrl || '').replace(/\/+$/, '');
+  if (base.endsWith('/api') && pathname.startsWith('/api/')) {
+    pathname = pathname.slice('/api'.length) || '/';
+  }
+  return `${pathname}${parsed.search}`;
+}
+
+function summarizeBackendApiPayload(payload) {
+  if (payload === undefined || payload === null) return 'none';
+  if (typeof payload === 'string') return truncateSingleLine(payload, 120);
+  try {
+    return truncateSingleLine(JSON.stringify(payload), 120);
+  } catch (_) {
+    return truncateSingleLine(String(payload), 120);
+  }
+}
+
+function summarizeBackendApiResponse(response) {
+  if (!response) return '';
+  if (response.data !== undefined && response.data !== null) {
+    try {
+      return truncateSingleLine(JSON.stringify(response.data), 120);
+    } catch (_) {
+      return truncateSingleLine(String(response.data), 120);
+    }
+  }
+  return truncateSingleLine(response.text || response.error || '', 120);
+}
+
+function formatBackendApiReceipt(call) {
+  return `backend_api ${String(call.method || 'get').toLowerCase()} ${call.endpoint} status ${call.status}: ${truncateSingleLine(call.summary, 120)}`;
+}
+
+function formatBackendApiApprovalPrompt(call) {
+  return `approve backend_api ${String(call.method || 'post').toLowerCase()} ${call.endpoint} payload ${summarizeBackendApiPayload(call.payload)}? yes/no: `;
+}
+
+function messageApprovesBackendApi(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[.!?]+$/g, '');
+  return normalized === 'yes' || normalized === 'y';
+}
+
+async function requestBackendApiApproval(call, options = {}) {
+  const prompt = formatBackendApiApprovalPrompt(call);
+  if (typeof options.approveBackendApi === 'function') {
+    if (options.output && typeof options.output.write === 'function') {
+      options.output.write(`${prompt}\n`);
+    }
+    const decision = await options.approveBackendApi({ ...call, prompt });
+    return decision === true || messageApprovesBackendApi(decision);
+  }
+
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  if (!input || !input.isTTY) return false;
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(messageApprovesBackendApi(answer));
+    });
+  });
+}
+
+function backendApiToolDescriptor() {
+  return {
+    name: BACKEND_API_TOOL_NAME,
+    description: 'Call allowlisted AtrisOS backend API endpoints through ax. get calls run directly; non-get calls require explicit user approval.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        method: { type: 'string', description: 'HTTP method, for example get or post' },
+        endpoint: { type: 'string', description: 'Allowlisted endpoint such as /api/atris2/health or /api/improve' },
+        payload: { type: 'object', description: 'JSON payload for non-get calls' },
+      },
+      required: ['endpoint'],
+    },
+    allowlist: BACKEND_API_ALLOWLIST.map(row => ({ method: row.method, endpoint: row.endpoint, description: row.description })),
+  };
+}
+
+async function executeBackendApiTool(args = {}, options = {}) {
+  const method = normalizeBackendApiMethod(args.method || args.verb);
+  const normalizedEndpoint = normalizeBackendApiEndpoint(args.endpoint || args.path || args.url);
+  if (!normalizedEndpoint) {
+    return { status: 'error', error: 'backend_api refused: missing or invalid endpoint' };
+  }
+
+  const allowlisted = backendApiAllowlistEntry(method, normalizedEndpoint.pathname);
+  if (!allowlisted) {
+    return {
+      status: 'error',
+      error: `backend_api refused: ${method.toLowerCase()} ${normalizedEndpoint.endpoint} is not allowlisted`,
+    };
+  }
+
+  const payload = args.payload !== undefined ? args.payload : args.body;
+  const call = { method, endpoint: normalizedEndpoint.endpoint, payload };
+  if (method !== 'GET') {
+    const approved = await requestBackendApiApproval(call, options);
+    if (!approved) {
+      return {
+        status: 'error',
+        error: `backend_api refused: ${method.toLowerCase()} ${normalizedEndpoint.endpoint} was not approved`,
+      };
+    }
+  }
+
+  const loadCreds = options.loadCredentials || loadCredentials;
+  const credentials = loadCreds();
+  const token = credentials && credentials.token ? credentials.token : '';
+  if (!token) {
+    return { status: 'error', error: 'backend_api refused: not logged in' };
+  }
+
+  const apiFn = options.apiRequestJson || apiRequestJson;
+  const baseFn = options.getApiBaseUrl || getApiBaseUrl;
+  const requestPath = apiRequestPathForBackendEndpoint(normalizedEndpoint.endpoint, baseFn());
+  const response = await apiFn(requestPath, {
+    method,
+    token,
+    ...(method === 'GET' ? {} : { body: payload === undefined ? {} : payload }),
+    timeoutMs: options.timeoutMs || 30000,
+  });
+  const summary = summarizeBackendApiResponse(response);
+  const receipt = formatBackendApiReceipt({
+    method,
+    endpoint: normalizedEndpoint.endpoint,
+    status: response && typeof response.status === 'number' ? response.status : 0,
+    summary,
+  });
+  return {
+    status: response && response.ok ? 'ok' : 'error',
+    method: method.toLowerCase(),
+    endpoint: normalizedEndpoint.endpoint,
+    status_code: response && typeof response.status === 'number' ? response.status : 0,
+    summary,
+    receipt,
+    response: response && response.data !== undefined && response.data !== null
+      ? response.data
+      : truncateSingleLine(response && response.text, 4000),
+    ...(response && response.ok ? {} : { error: (response && response.error) || summary || 'request failed' }),
+  };
+}
+
 function defaultAuthority(id) {
   const key = canonicalConnectorId(id);
   if (key === 'gmail') return { list_messages: 'read_only', get_message: 'read_only', send_message: 'approval_required' };
@@ -687,10 +957,38 @@ function normalizeMode(mode) {
   return mode === 'fast' ? 'fast' : 'pro';
 }
 
+function appendAutoPick(message, picked, options = {}) {
+  try {
+    const dir = path.join(os.homedir(), '.atris');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'ax-auto-picks.jsonl'), `${JSON.stringify({
+      at: new Date().toISOString(),
+      lane: picked.lane,
+      reason: picked.reason,
+      message_chars: String(message || '').length,
+      print: Boolean(options.print),
+    })}\n`);
+  } catch (_) {
+    // Lane telemetry is best-effort and must never block a turn.
+  }
+}
+
+function autoLaneForMessage(message, options = {}) {
+  const picked = pickLane(message);
+  appendAutoPick(message, picked, options);
+  const errorOutput = options.errorOutput || process.stderr;
+  errorOutput.write(`${picked.reason}\n`);
+  return picked;
+}
+
 function formatPrompt(mode, options = {}) {
   if (!mode) return '› ';
   const tier = normalizeMode(mode);
-  return `${paint(tier, [ANSI.bold, tierColor(tier)], options)} › `;
+  const label = paint(tier, [ANSI.bold, tierColor(tier)], options);
+  if (options.approveMode === 'auto') {
+    return `${label} ${paint('[auto-approve]', [ANSI.muted], options)} › `;
+  }
+  return `${label} › `;
 }
 
 const TIER_COMMANDS = new Map([
@@ -707,6 +1005,8 @@ const CHAT_COMMANDS = [
   ['/fast', 'quick answers, lowest latency'],
   ['/pro', 'deeper tool loop for real work'],
   ['/max', 'highest reasoning for the hardest jobs'],
+  ['/clear', 'wipe chat history and reset conversation id'],
+  ['/context', 'show turn count and rough token estimate'],
   ['/help', 'show this menu'],
   ['exit', 'leave chat'],
 ];
@@ -867,6 +1167,8 @@ function formatGoalStatusLine(goal, options = {}) {
   const status = String(goal.mission_status || '').toLowerCase();
   if (!['active', 'running', 'planning', 'in_progress', 'ready'].includes(status)) return '';
   const elapsed = goalElapsedSeconds(goal);
+  // A goal "running" for >24h is stale state, not a live goal — hide it.
+  if (elapsed !== null && elapsed > 86400) return '';
   const objective = String(goal.objective).length > 64
     ? `${String(goal.objective).slice(0, 61)}...`
     : String(goal.objective);
@@ -1768,12 +2070,58 @@ async function approveWorkspaceApproval(ref, options = {}) {
   return { response, executed };
 }
 
+// A persistent grant (ax --grant) lets an exact approved command pattern
+// redeem itself on later turns instead of re-asking; anything unmatched
+// falls through to the normal hint. Store: ~/.atris/permission-grants.json.
+async function autoRedeemGrantedApprovals(cwd, sinceMs, options = {}) {
+  const redeemed = [];
+  for (const item of pendingWorkspaceApprovalsSince(cwd, sinceMs)) {
+    const record = item.record;
+    if (String(record.action_type || '') !== 'local_command') continue;
+    const command = record.payload && record.payload.command;
+    const grant = permissionGrants.matchGrant({ command, workspaceRoot: cwd });
+    if (!grant) continue;
+    const output = options.output || process.stdout;
+    output.write(`${formatAuxRow('grant', `auto-approved via ${grant.grant_id}: ${grant.pattern.display}`, output)}\n`);
+    try {
+      await approveWorkspaceApproval(record.approval_id, { ...options, cwd, output });
+      permissionGrants.recordUse(grant.grant_id);
+      redeemed.push(record.approval_id);
+    } catch {
+      // Redemption failed: leave the artifact pending so the hint still shows.
+    }
+  }
+  return redeemed;
+}
+
 function writeWorkspaceApprovalHints(cwd, sinceMs, output) {
   for (const item of pendingWorkspaceApprovalsSince(cwd, sinceMs)) {
     output.write(`${formatAuxRow('approve', formatApprovalCommand(item.record.approval_id), output)}\n`);
   }
 }
 
+function deferWriteWorkspaceApprovalHints(cwd, sinceMs, output) {
+  setImmediate(() => {
+    Promise.resolve()
+      .then(() => writeWorkspaceApprovalHints(cwd, sinceMs, output))
+      .catch(() => {});
+  });
+}
+
+function deferPersistPendingApproval(receipt, approvalRequest, options = {}) {
+  setImmediate(() => {
+    Promise.resolve()
+      .then(() => persistPendingApproval(receipt, approvalRequest, options))
+      .catch(() => {});
+  });
+}
+
+function estimateHistoryContext(history = []) {
+  const turns = history.filter(row => row && row.role === 'user').length;
+  const chars = history.reduce((total, row) => total + String((row && row.content) || '').length, 0);
+  return { turns, chars, tokens: Math.ceil(chars / 4) };
+}
+
 function formatStoredApprovals(store, options = {}) {
   const approvals = Array.isArray(store && store.approvals) ? store.approvals : [];
   if (!approvals.length) return 'No pending approvals.';
@@ -2187,8 +2535,9 @@ function buildPayload(message, options = {}) {
   const payload = {
     message: buildMessage(message, options.history || []),
     model: modelForMode(mode),
-    max_turns: local ? (mode === 'fast' ? 8 : 14) : 1,
-    verify_command: verifyCommand || 'true'
+    max_turns: local ? (mode === 'fast' ? 16 : 24) : 1,
+    verify_command: verifyCommand || 'true',
+    local_tools: [backendApiToolDescriptor()]
   };
   if (previousMessages.length) {
     payload.previous_messages = previousMessages;
@@ -2317,7 +2666,15 @@ function handleEvent(event, state, output) {
       state.relay.chain = state.relay.chain
         .then(() => state.relay.execute(event.name, args))
         .catch((err) => ({ status: 'error', error: String(err.message || err).slice(0, 500) }))
-        .then((result) => state.relay.post(event.call_id, result))
+        .then((result) => {
+          if (result && result.receipt) {
+            flushPendingText(state, output);
+            writeAuxLine(state, output, formatAuxRow('receipt', result.receipt, output));
+            state.lastAux = 'receipt';
+          }
+          return result;
+        })
+        .then((result) => state.relay.post(event.call_id || event.id, result))
         .catch((err) => state.errors.push(`tool relay failed: ${err.message}`));
     }
     return;
@@ -2351,11 +2708,22 @@ function handleEvent(event, state, output) {
     return;
   }
 
-  if (event.type === 'result' && event.result && !state.output) {
+  if (event.type === 'result' && event.result) {
     const content = String(event.result || '');
-    state.output += content;
-    if (output && output.isTTY) writeStreamingText(state, output, content);
-    else state.pendingText += content;
+    // `result` is the backend's authoritative final answer for the turn.
+    // Local tool-loop turns stream throwaway narration via text_delta before
+    // the model actually does the work ("Acknowledged, let me check that...")
+    // — remember the true final text separately so callers (runHeadlessTurn's
+    // JSON `output`, and chat()'s conversation history) get the real answer
+    // instead of whichever fragment happened to stream first. Terminal
+    // rendering keeps its existing de-dupe: only print `result` live when
+    // nothing was already streamed (avoids double-printing a duplicate).
+    state.resultOutput = content;
+    if (!state.output) {
+      state.output += content;
+      if (output && output.isTTY) writeStreamingText(state, output, content);
+      else state.pendingText += content;
+    }
     return;
   }
 
@@ -2385,14 +2753,7 @@ async function postTurn(message, options = {}) {
   const payload = buildPayload(message, { ...options, route, connectionContext, connectionUserId, turnId });
   const postData = JSON.stringify(payload);
   const output = options.output || process.stdout;
-  // Relayed business turns wait on EC2 terminal calls (up to 60s each) with no
-  // SSE traffic in between, so the socket-idle timeout needs more headroom.
-  const baseTimeoutMs = payload.model === 'atris:max' ? 300000 : payload.model === 'atris:pro' ? 180000 : 60000;
-  let timeoutMs = options.business ? Math.max(baseTimeoutMs, 180000) : baseTimeoutMs;
-  // Local workspace tool loops (max_turns 8/14) legitimately run past the fast
-  // lane's 60s chat wall — SwapBench 2026-07-02: three tool-loop tasks died at
-  // ~60s as "Atris cloud did not respond". Same headroom as business relays.
-  if (local) timeoutMs = Math.max(timeoutMs, 180000);
+  const timeoutMs = postTurnTimeoutMs(payload, { business: options.business, local });
   const turnUrl = new URL(backendUrl({ route: endpointRoute }));
   const transport = turnUrl.protocol === 'https:' ? https : http;
   const state = {
@@ -2411,11 +2772,34 @@ async function postTurn(message, options = {}) {
     markdownMode: 'normal',
     markdownBuffer: '',
     markdownCarry: '',
-    relay: options.business ? {
+    relay: {
       chain: Promise.resolve(),
-      execute: options.business.executor,
-      post: (callId, result) => options.business.postToolResult(callId, result, backendBaseUrl({ route: 'cloud' }))
-    } : null
+      execute: async (name, args) => {
+        if (name === BACKEND_API_TOOL_NAME) {
+          return executeBackendApiTool(args, {
+            input: options.input,
+            output,
+            approveBackendApi: options.approveBackendApi,
+            apiRequestJson: options.apiRequestJson,
+            loadCredentials: options.loadCredentials,
+            getApiBaseUrl: options.getApiBaseUrl,
+            timeoutMs: options.backendApiTimeoutMs,
+          });
+        }
+        if (options.business) return options.business.executor(name, args);
+        return { status: 'error', error: `unsupported relayed tool: ${name || '?'}` };
+      },
+      post: (callId, result) => {
+        if (options.business) {
+          return options.business.postToolResult(callId, result, backendBaseUrl({ route: 'cloud' }));
+        }
+        return postJson(BACKEND_API_TOOL_RESULT_PATH, { call_id: callId, result }, {
+          token,
+          route: endpointRoute,
+          timeoutMs: 30000,
+        });
+      }
+    }
   };
 
   return new Promise((resolve, reject) => {
@@ -2495,6 +2879,11 @@ async function postTurn(message, options = {}) {
         }
 
         flushPendingText(state, output);
+        // Terminal display already streamed/de-duped above; the RETURNED
+        // output must be the backend's authoritative final answer, not
+        // whichever text_delta fragment happened to arrive first (see the
+        // `result` branch in handleEvent).
+        if (state.resultOutput) state.output = state.resultOutput;
         finish(null, state);
       });
     });
@@ -2622,6 +3011,44 @@ function turnFunctionForMode(mode) {
   return normalizeMode(mode) === 'code-fast' ? postCodeFastTurn : postTurn;
 }
 
+async function runHeadlessTurn(message, options = {}) {
+  const mode = normalizeMode(options.mode || 'fast');
+  const startedAt = Date.now();
+  const sink = options.output || bufferedOutput();
+  const turnFunction = options.turnFunction || turnFunctionForMode(mode);
+  const autoFields = options.autoLane && options.autoReason
+    ? { auto_lane: normalizeMode(options.autoLane), auto_reason: String(options.autoReason) }
+    : {};
+
+  try {
+    const result = await turnFunction(message, {
+      mode,
+      cwd: options.cwd || process.cwd(),
+      route: options.route,
+      business: options.business,
+      verify: options.verify,
+      output: sink,
+      showProgress: false,
+    });
+    return {
+      ok: true,
+      model: modelForMode(mode),
+      output: String((result && result.output) || '').trim(),
+      durationMs: Number((result && result.durationMs) || 0) || (Date.now() - startedAt),
+      ...autoFields,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      model: modelForMode(mode),
+      output: '',
+      durationMs: Date.now() - startedAt,
+      error: String((error && error.message) || error || 'headless turn failed'),
+      ...autoFields,
+    };
+  }
+}
+
 async function chat(options = {}) {
   let mode = normalizeMode(options.mode);
   const cwd = options.cwd || process.cwd();
@@ -2631,7 +3058,9 @@ async function chat(options = {}) {
   const output = logger ? logger.output : baseOutput;
   const history = [];
   let lastCompactionNotice = 0;
-  const conversationId = options.conversationId || `ax-${process.pid}-${Date.now().toString(36)}`;
+  let conversationId = options.conversationId || `ax-${process.pid}-${Date.now().toString(36)}`;
+  const session = { approveMode: 'stage' };
+  let turnInFlight = false;
 
   output.write(`${formatHeader({ mode, cwd, chat: true }, output)}\n\n`);
   if (logger) output.write(`${formatAuxRow('log', formatPathSubject(logger.path, output), output)}\n\n`);
@@ -2678,11 +3107,31 @@ async function chat(options = {}) {
       return false;
     }
 
+    if (trimmed === '/clear') {
+      history.length = 0;
+      conversationId = `ax-${process.pid}-${Date.now().toString(36)}`;
+      output.write(`${paint('context cleared', [ANSI.muted], output)}\n\n`);
+      return false;
+    }
+
+    if (trimmed === '/context') {
+      const ctx = estimateHistoryContext(history);
+      output.write(`${paint(`· ${ctx.turns} turn${ctx.turns === 1 ? '' : 's'} · ~${ctx.chars} chars · ~${ctx.tokens} tokens`, [ANSI.muted], output)}\n\n`);
+      return false;
+    }
+
     if (trimmed.startsWith('/')) {
       output.write(`${chatMenu(output)}\n\n`);
       return false;
     }
 
+    if (options.auto) {
+      mode = autoLaneForMessage(trimmed, {
+        errorOutput: options.errorOutput,
+        print: false,
+      }).lane;
+    }
+
     if (logger) logger.write(`${formatPrompt(mode)}${trimmed}\n`);
     output.write('\n');
 
@@ -2781,7 +3230,22 @@ async function chat(options = {}) {
       lastCompactionNotice = compactedTurns;
       output.write(`${paint(`· context: ${compactedTurns} earlier turn${compactedTurns === 1 ? '' : 's'} compacted into a digest`, [ANSI.muted], output)}\n`);
     }
-    const result = await turnFunction(trimmed, { mode, cwd, history, output, route, business: options.business, verify: options.verify, conversationId, turnId });
+    const result = await turnFunction(trimmed, {
+      mode,
+      cwd,
+      history,
+      input,
+      output,
+      route,
+      business: options.business,
+      verify: options.verify,
+      conversationId,
+      turnId,
+      approveBackendApi: options.approveBackendApi,
+      apiRequestJson: options.apiRequestJson,
+      loadCredentials: options.loadCredentials,
+      getApiBaseUrl: options.getApiBaseUrl,
+    });
     if (result.output && !result.output.endsWith('\n')) output.write('\n');
     const approvalExecution = normalizeMode(mode) === 'code-fast'
       ? null
@@ -3595,11 +4059,22 @@ async function main() {
     args.splice(verifyIdx, 2);
   }
 
-  const mode = args.includes('--code-fast') || args.includes('--code') ? 'code-fast' : args.includes('--max') ? 'max' : args.includes('--fast') ? 'fast' : 'pro';
+  const explicitLane = args.includes('--code-fast') || args.includes('--code')
+    ? 'code-fast'
+    : args.includes('--max')
+      ? 'max'
+      : args.includes('--fast')
+        ? 'fast'
+        : args.includes('--pro')
+          ? 'pro'
+          : null;
+  const autoEnabled = args.includes('--auto') && !explicitLane;
+  let mode = explicitLane || 'pro';
   const doctor = args.includes('--doctor');
   const selfTest = args.includes('--self-test');
   const benchmark = args.includes('--benchmark');
   const approvals = args.includes('--approvals');
+  const printMode = args.includes('--print') || args.includes('--headless');
   const forceCloud = args.includes('--cloud');
   const forceLocal = args.includes('--local');
 
@@ -3614,6 +4089,34 @@ async function main() {
     args.splice(approveIdx, 2);
   }
 
+  let grantId = '';
+  const grantIdx = args.indexOf('--grant');
+  if (grantIdx !== -1) {
+    grantId = String(args[grantIdx + 1] || '').trim();
+    if (!grantId) {
+      console.error('Usage: ax --grant <approval-id>');
+      process.exit(1);
+    }
+    args.splice(grantIdx, 2);
+  }
+
+  const listGrants = args.includes('--grants');
+  if (listGrants) args.splice(args.indexOf('--grants'), 1);
+
+  const syncGrantsFlag = args.includes('--sync-grants');
+  if (syncGrantsFlag) args.splice(args.indexOf('--sync-grants'), 1);
+
+  let revokeGrantId = '';
+  const revokeGrantIdx = args.indexOf('--revoke-grant');
+  if (revokeGrantIdx !== -1) {
+    revokeGrantId = String(args[revokeGrantIdx + 1] || '').trim();
+    if (!revokeGrantId) {
+      console.error('Usage: ax --revoke-grant <grant-id>');
+      process.exit(1);
+    }
+    args.splice(revokeGrantIdx, 2);
+  }
+
   let denyId = '';
   const denyIdx = args.indexOf('--deny');
   if (denyIdx !== -1) {
@@ -3627,11 +4130,11 @@ async function main() {
 
   const route = forceCloud ? 'cloud' : forceLocal ? 'local' : 'auto';
   const prompt = args
-    .filter(arg => !['--max', '--fast', '--pro', '--code-fast', '--code', '--chat', '--doctor', '--approvals', '--self-test', '--benchmark', '--local', '--cloud', '--help', '-h'].includes(arg))
+    .filter(arg => !['--auto', '--max', '--fast', '--pro', '--code-fast', '--code', '--chat', '--doctor', '--approvals', '--self-test', '--benchmark', '--print', '--headless', '--local', '--cloud', '--help', '-h'].includes(arg))
     .join(' ')
     .trim();
 
-  const missionIntent = missionRunIntentFromMessage(prompt);
+  const missionIntent = printMode ? null : missionRunIntentFromMessage(prompt);
   if (missionIntent) {
     const result = await runLocalMission(missionIntent, {
       cwd: process.cwd(),
@@ -3649,6 +4152,12 @@ async function main() {
     return;
   }
 
+  const startsChat = !printMode && (!prompt || args.includes('--chat'));
+  const autoPick = autoEnabled && prompt && !startsChat
+    ? autoLaneForMessage(prompt, { print: printMode })
+    : null;
+  if (autoPick) mode = autoPick.lane;
+
   let business = null;
   if (businessSlug) {
     if (normalizeMode(mode) === 'code-fast') {
@@ -3677,7 +4186,7 @@ async function main() {
       executor: makeCloudExecutor({ token: creds.token, businessId: biz.businessId, workspaceId: biz.workspaceId, slug: businessSlug }),
       postToolResult
     };
-    console.log(`cloud workspace: ${biz.businessName || businessSlug}`);
+    if (!printMode) console.log(`cloud workspace: ${biz.businessName || businessSlug}`);
   }
 
   try {
@@ -3720,8 +4229,75 @@ async function main() {
       return;
     }
 
+    if (grantId) {
+      const found = findWorkspaceApproval(grantId, process.cwd());
+      if (!found) {
+        console.error(`Pending approval not found: ${grantId}`);
+        process.exit(1);
+      }
+      const command = found.record.payload && found.record.payload.command;
+      const added = permissionGrants.addGrant({ command, workspaceRoot: process.cwd() });
+      if (!added.ok) {
+        console.error(`Not grantable: ${added.reason}`);
+        process.exit(1);
+      }
+      console.log(`granted ${added.grant.grant_id}: ${added.grant.pattern.display} (this workspace, expires ${added.grant.constraints.expires_at.slice(0, 10)})`);
+      await approveWorkspaceApproval(grantId, { cwd: process.cwd(), mode, output: process.stdout });
+      return;
+    }
+
+    if (listGrants) {
+      const store = permissionGrants.loadGrants();
+      const rows = store.grants.filter(g => g.status === 'active');
+      if (!rows.length) {
+        console.log('no active grants');
+      } else {
+        for (const g of rows) {
+          console.log(`${g.grant_id}  ${g.pattern.display}  ${g.scope.workspace_root}  uses:${g.audit?.use_count || 0}  expires:${String(g.constraints?.expires_at || '').slice(0, 10)}`);
+        }
+      }
+      return;
+    }
+
+    if (revokeGrantId) {
+      const revoked = permissionGrants.revokeGrant(revokeGrantId);
+      if (!revoked.ok) {
+        console.error(revoked.reason);
+        process.exit(1);
+      }
+      console.log(`revoked ${revoked.grant.grant_id}: ${revoked.grant.pattern.display}`);
+      return;
+    }
+
+    if (syncGrantsFlag) {
+      const { apiRequestJson } = require('./utils/api');
+      const result = await permissionGrants.syncGrants({ apiRequestJson, token: authToken() });
+      if (!result.ok) {
+        console.error(`grant sync failed: ${result.reason}`);
+        process.exit(1);
+      }
+      console.log(`synced grants: pushed:${result.pushed} pulled:${result.pulled} revoked:${result.revoked}${result.rejected ? ` rejected:${result.rejected}` : ''}`);
+      return;
+    }
+
+    if (printMode) {
+      const payload = prompt
+        ? await runHeadlessTurn(prompt, {
+          mode,
+          cwd: process.cwd(),
+          route: route === 'auto' ? undefined : route,
+          business,
+          verify,
+          autoLane: autoPick && autoPick.lane,
+          autoReason: autoPick && autoPick.reason,
+        })
+        : { ok: false, model: modelForMode(mode), output: '', durationMs: 0, error: 'missing prompt' };
+      console.log(JSON.stringify(payload));
+      process.exit(payload.ok ? 0 : 1);
+    }
+
     if (!prompt || args.includes('--chat')) {
-      await chat({ mode, cwd: process.cwd(), route: route === 'auto' ? undefined : route, business, verify });
+      await chat({ mode, cwd: process.cwd(), route: route === 'auto' ? undefined : route, business, verify, auto: autoEnabled });
       return;
     }
 
@@ -3737,7 +4313,9 @@ async function main() {
       : null;
     if (approvalRecord) console.log(formatAuxRow('approve', formatApprovalCommand(approvalRecord.id), process.stdout));
     // A one-shot has no next turn, so "reply yes to approve" is a dead end;
-    // surface the exact redeem command for anything the turn staged on disk.
+    // granted patterns redeem themselves, everything else gets the exact
+    // redeem command for what the turn staged on disk.
+    await autoRedeemGrantedApprovals(process.cwd(), turnStartedAt, { mode, output: process.stdout });
     writeWorkspaceApprovalHints(process.cwd(), turnStartedAt, process.stdout);
     console.log('');
     console.log(formatDoneLine(result.durationMs, creditsFromState(result)));
@@ -3767,10 +4345,13 @@ module.exports = {
   approvalStorePath,
   approveStoredApproval,
   approveWorkspaceApproval,
+  autoRedeemGrantedApprovals,
   findWorkspaceApproval,
   listWorkspaceApprovals,
   pendingWorkspaceApprovalsSince,
   backendBaseUrl,
+  backendApiAllowlistEntry,
+  backendApiToolDescriptor,
   backendStartCommand,
   backendUrl,
   buildCodeFastPayload,
@@ -3793,6 +4374,9 @@ module.exports = {
   denyStoredApproval,
   executeApprovalRequest,
   executeApprovalFromState,
+  executeBackendApiTool,
+  formatBackendApiApprovalPrompt,
+  formatBackendApiReceipt,
   formatDoneLine,
   formatDuration,
   formatApprovalExecutionResult,
@@ -3819,11 +4403,13 @@ module.exports = {
   postApprovalExecution,
   postCodeFastTurn,
   postTurn,
+  postTurnTimeoutMs,
   readApprovalStore,
   removeStoredApproval,
   renderStreamingMarkdown,
   renderTerminalMarkdown,
   resolveRoute,
+  runHeadlessTurn,
   runBenchmark,
   runSelfTest,
   runtimeReadyForChat,