incremnt 0.7.2 → 0.8.1

package/src/contract.js

@@ -1,4 +1,4 @@
-export const contractVersion = 17;
+export const contractVersion = 21;
 
 export const capabilities = {
   readOnly: false,
@@ -6,7 +6,9 @@ export const capabilities = {
   remoteReads: true,
   remoteWrites: true,
   remoteAuthShell: true,
-  remoteBootstrap: true
+  remoteBootstrap: true,
+  agentTokens: true,
+  cliSessionRefresh: true
 };
 
 // Single source of truth for all read commands.
@@ -77,6 +79,18 @@ export const commandSchema = [
       { name: 'id', type: 'string', format: 'id', required: false, description: 'Program ID (defaults to active program)' }
     ]
   },
+  {
+    command: 'programs progress',
+    id: 'program-progress',
+    description: 'Summarize active program progress using cycle and exercise evidence',
+    supportsFields: true,
+    agentNotes: 'Use for broad program progress questions. Returns compact first/best/latest exercise evidence plus cycle and training-load context.',
+    options: [
+      { name: 'program-id', type: 'string', format: 'id', required: false, description: 'Program ID (defaults to active program)' },
+      { name: 'since', type: 'string', required: false, description: 'Start date for progress window (YYYY-MM-DD)' },
+      { name: 'limitExercises', type: 'number', required: false, description: 'Max exercise rows to return (default 10, max 50)' }
+    ]
+  },
   {
     command: 'exercises history',
     id: 'exercise-history',
@@ -87,6 +101,19 @@ export const commandSchema = [
       { name: 'name', type: 'string', required: true, description: 'Exercise name' }
     ]
   },
+  {
+    command: 'exercises progress',
+    id: 'exercise-progress-summary',
+    description: 'Summarize exercise first/best/latest progress over a date window',
+    supportsFields: true,
+    agentNotes: 'Use for longitudinal progress questions such as "what improved since January". Omit --name to summarize active-program exercises.',
+    options: [
+      { name: 'name', type: 'string', required: false, description: 'Exercise name to scope progress' },
+      { name: 'since', type: 'string', required: false, description: 'Start date for progress window (YYYY-MM-DD)' },
+      { name: 'program-id', type: 'string', format: 'id', required: false, description: 'Program ID used to scope exercise names' },
+      { name: 'limit', type: 'number', required: false, description: 'Max exercise rows to return (default 12, max 50)' }
+    ]
+  },
   {
     command: 'records',
     id: 'records',
@@ -130,6 +157,16 @@ export const commandSchema = [
       { name: 'id', type: 'string', format: 'id', required: true, description: 'Cycle summary ID' }
     ]
   },
+  {
+    command: 'cycles progress',
+    id: 'cycle-progression-summary',
+    description: 'Summarize cycle progression counts and adherence',
+    supportsFields: true,
+    options: [
+      { name: 'program-id', type: 'string', format: 'id', required: false, description: 'Filter by program ID' },
+      { name: 'limit', type: 'number', required: false, description: 'Max cycles to return (default 8, max 20)' }
+    ]
+  },
   {
     command: 'health summary',
     id: 'health-summary',
@@ -151,6 +188,15 @@ export const commandSchema = [
     description: 'Training load analysis (7-day vs 28-day comparison, effort scores, readiness via ATL/CTL/TSB, per-type breakdown)',
     options: []
   },
+  {
+    command: 'training profile',
+    id: 'training-profile',
+    description: 'Summarize stable lifter profile evidence from logs and current program',
+    supportsFields: true,
+    options: [
+      { name: 'since', type: 'string', required: false, description: 'Start date for profile window (YYYY-MM-DD)' }
+    ]
+  },
   {
     command: 'ask history',
     id: 'ask-history',
@@ -209,7 +255,7 @@ export const commandSchema = [
     id: 'coach-observations-current',
     description: 'List current persisted coach observations',
     supportsFields: true,
-    agentNotes: 'Read-only persisted insight surface. Returns generated/seen observations with evidence and lifecycle status. Use IDs from this command for CLI seen/dismiss actions.',
+    agentNotes: 'Read-only persisted insight surface. Returns generated/seen observations with evidence, lifecycle status, outcome tracking, and user feedback status. Use IDs from this command for CLI seen/dismiss/outcome/feedback actions.',
     options: [
       { name: 'limit', type: 'number', required: false, description: 'Max observations to return (default 5, max 20)' }
     ]
@@ -232,6 +278,7 @@ export const writeCommandSchema = [
     command: 'programs proposals',
     id: 'programs-proposals',
     description: 'List program proposals',
+    requiredAccess: 'read',
     agentNotes: 'Pass --status to filter. Use this before programs proposal dismiss to look up proposal IDs.',
     options: [
       { name: 'status', type: 'string', format: 'enum', enum: ['pending', 'accepted', 'dismissed'], required: false, description: 'Filter by status (pending, accepted, dismissed)' }
@@ -264,6 +311,7 @@ export const writeCommandSchema = [
     id: 'program-share-list',
     description: 'List share artifacts for one program',
     usage: 'programs share list --program-id <program-id>',
+    requiredAccess: 'read',
     agentNotes: 'Returns existing share-ids for the program. Use this to look up share-id before programs share revoke — the public token is NOT the share-id.',
     options: [
       { name: 'program-id', type: 'string', format: 'id', required: true, description: 'Program ID' }
@@ -315,11 +363,65 @@ export const writeCommandSchema = [
     options: [
       { name: 'id', type: 'string', format: 'id', required: true, description: 'Observation ID' }
     ]
+  },
+  {
+    command: 'coach observations outcome',
+    id: 'coach-observations-outcome',
+    description: 'Record whether a coach observation recommendation worked',
+    usage: 'coach observations outcome --id <observation-id> --status <improved|unchanged|regressed|inconclusive>',
+    dryRun: true,
+    mcp: false,
+    agentNotes: 'Mutation. Records recommendation outcome on the original coach_observations row so later Ask Coach turns can compare new sessions against prior advice. Does not change seen/dismissed lifecycle state.',
+    options: [
+      { name: 'id', type: 'string', format: 'id', required: true, description: 'Observation ID' },
+      { name: 'status', type: 'string', format: 'enum', enum: ['improved', 'unchanged', 'regressed', 'inconclusive'], required: true, description: 'Observed recommendation outcome' },
+      { name: 'observedAt', type: 'string', required: false, description: 'Optional ISO timestamp for when the outcome was observed' },
+      { name: 'notes', type: 'string', required: false, description: 'Optional outcome notes' },
+      { name: 'linkedFollowupObservationId', type: 'string', format: 'id', required: false, description: 'Optional follow-up observation ID connected to the outcome' }
+    ]
+  },
+  {
+    command: 'coach observations feedback',
+    id: 'coach-observations-feedback',
+    description: 'Record whether the user accepted or rejected a coach observation',
+    usage: 'coach observations feedback --id <observation-id> --status <accepted|rejected>',
+    dryRun: true,
+    mcp: false,
+    agentNotes: 'Mutation. Records explicit user agreement/disagreement separately from seen/dismissed visibility state.',
+    options: [
+      { name: 'id', type: 'string', format: 'id', required: true, description: 'Observation ID' },
+      { name: 'status', type: 'string', format: 'enum', enum: ['accepted', 'rejected'], required: true, description: 'User feedback status' },
+      { name: 'feedbackAt', type: 'string', required: false, description: 'Optional ISO timestamp for when feedback was recorded' }
+    ]
+  },
+  {
+    command: 'ask',
+    id: 'ask',
+    description: 'Ask the AI coach a question and return the answer',
+    usage: 'ask --question "How is my bench progressing?" [--conversation-id <id>] [--tone default|hype|numbers-only] [--exclude <items>] [--history <json>]',
+    dryRun: false,
+    mcp: true,
+    agentNotes: 'Mutation. Calls the remote Ask Coach pipeline; persists the conversation server-side. If --conversation-id is omitted, a new UUID is generated and returned in the response. Pass --history as JSON to continue an existing conversation. Tone defaults to "default".',
+    options: [
+      { name: 'question', type: 'string', required: true, maxLength: 500, description: 'Question text (1-500 chars)' },
+      { name: 'conversation-id', type: 'string', format: 'id', required: false, description: 'Conversation ID (auto-generated if omitted)' },
+      { name: 'history', type: 'string', required: false, description: 'Prior conversation turns as JSON array of {role, content}' },
+      { name: 'exclude', type: 'string', required: false, description: 'Comma-separated AI privacy exclusions (e.g. coach_observations)' },
+      { name: 'tone', type: 'string', format: 'enum', enum: ['default', 'hype', 'numbers-only'], required: false, description: 'Response tone (default: default)' }
+    ]
   }
 ];
 
 export const writeCommands = new Set(writeCommandSchema.map((c) => c.id));
 
+for (const command of commandSchema) {
+  command.requiredAccess ??= 'read';
+}
+
+for (const command of writeCommandSchema) {
+  command.requiredAccess ??= 'write';
+}
+
 export const proposalSchema = {
   description: 'JSON structure for programs propose --file. Weights are omitted — iOS calculates from history.',
   required: ['name', 'equipmentTier', 'days'],
@@ -354,6 +456,56 @@ export const proposalSchema = {
   }
 };
 
+// Describes how token scope gates commands, so an agent can decide before
+// calling rather than discovering limits reactively via a 403.
+export const accessModel = {
+  description: 'Agent tokens (incr_agent_*) carry an access scope. A command runs only if the active token satisfies its requiredAccess. Read tokens cannot run write commands.',
+  scopes: ['read', 'write'],
+  check: 'The active token access (status.auth.credential.access) must satisfy each command\'s requiredAccess (see schema/writeSchema entries).',
+  onInsufficientScope: 'A 403 with code INSUFFICIENT_SCOPE includes requiredAccess and requiresHuman:true. Minting a write token needs a human login — escalate rather than retry.'
+};
+
+// Structured definitions for the human-only `agents` token-management commands.
+// These are NOT registered as MCP tools and CANNOT be run by an agent token
+// (management requires a human session); they are described here so the command
+// surface is fully discoverable from `incremnt contract`.
+export const agentCommandSchema = [
+  {
+    id: 'agents-create',
+    command: 'agents create',
+    usage: 'agents create --name <name> [--access <read|write>] [--expires-days <n>] [--store]',
+    description: 'Mint a new headless agent token.',
+    requiresHuman: true,
+    agentNotes: 'An agent CANNOT run this — minting requires a human (non-agent-token) login. On INSUFFICIENT_SCOPE, escalate to an operator. The plaintext token is returned ONCE in agentToken.token; capture it immediately (tokenIssued:true even if local persistence fails). --store replaces the active CLI session with the new token.',
+    options: [
+      { name: 'name', type: 'string', required: true, description: 'Human-readable label for the token.' },
+      { name: 'access', type: 'string', format: 'enum', enum: ['read', 'write'], required: false, description: 'Token scope (default read). read = read-only; write = can mutate.' },
+      { name: 'expires-days', type: 'number', required: false, description: 'Days until expiry (1-3650, default 90).' },
+      { name: 'store', type: 'boolean', required: false, description: 'Persist the token as the active CLI session, replacing the current login.' }
+    ]
+  },
+  {
+    id: 'agents-list',
+    command: 'agents list',
+    usage: 'agents list',
+    description: 'List agent tokens for the account (never returns the secret).',
+    requiresHuman: true,
+    agentNotes: 'Returns token ids, hints, scopes and expiry — not the secret. Use the id with agents revoke.',
+    options: []
+  },
+  {
+    id: 'agents-revoke',
+    command: 'agents revoke',
+    usage: 'agents revoke --id <agent-token-id>',
+    description: 'Revoke an agent token by id.',
+    requiresHuman: true,
+    agentNotes: 'Use the id from agents list (the agt_... id, not the public token).',
+    options: [
+      { name: 'id', type: 'string', format: 'id', required: true, description: 'Agent token id (agt_...) to revoke.' }
+    ]
+  }
+];
+
 export const officialCommands = [
   ...commandSchema.map((c) => c.usage ?? c.command),
   ...writeCommandSchema.map((c) => c.usage ?? c.command),
@@ -366,7 +518,12 @@ export const officialCommands = [
   'login --snapshot <snapshot-file>',
   'login --base-url <base-url> --token <token>',
   'login --base-url <base-url> --email <email>',
+  'login --agent-token <token>',
   'login --session-file <session-file>',
+  'agents create --name <name>',
+  'agents create --name <name> --access <read|write>',
+  'agents list',
+  'agents revoke --id <agent-token-id>',
   'logout'
 ];
 

package/src/format.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { commandSchema, writeCommandSchema } from './contract.js';
+import { agentCommandSchema, commandSchema, writeCommandSchema } from './contract.js';
 
 const shortMonths = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const shortDays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
@@ -803,6 +803,15 @@ function formatCoachObservationsCurrent(payload) {
     lines.push(` ${chalk.bold(observation.title ?? observation.kind ?? 'Observation')}${status}${confidence}`);
     if (observation.summary) lines.push(`   ${observation.summary}`);
     if (observation.actionText) lines.push(`   ${chalk.dim('Action')} ${observation.actionText}`);
+    if (observation.outcomeStatus) {
+      const outcomeMeta = observation.outcomeObservedAt ? ` (${observation.outcomeObservedAt})` : '';
+      const outcomeNotes = observation.outcomeNotes ? ` ${observation.outcomeNotes}` : '';
+      lines.push(`   ${chalk.dim('Outcome')} ${observation.outcomeStatus}${outcomeMeta}${outcomeNotes}`);
+    }
+    if (observation.userFeedbackStatus) {
+      const feedbackMeta = observation.userFeedbackAt ? ` (${observation.userFeedbackAt})` : '';
+      lines.push(`   ${chalk.dim('Feedback')} ${observation.userFeedbackStatus}${feedbackMeta}`);
+    }
     if (observation.id) lines.push(`   ${chalk.dim(observation.id)}`);
     lines.push('');
   }
@@ -817,6 +826,18 @@ function formatCoachObservationMutation(payload) {
   return ` Coach observation ${chalk.bold(observation.id)} is ${chalk.bold(observation.status)}.`;
 }
 
+function formatCoachObservationOutcomeMutation(payload) {
+  const observation = payload?.observation;
+  if (!observation) return 'Coach observation not found.';
+  return ` Coach observation ${chalk.bold(observation.id)} outcome is ${chalk.bold(observation.outcomeStatus ?? 'unknown')}.`;
+}
+
+function formatCoachObservationFeedbackMutation(payload) {
+  const observation = payload?.observation;
+  if (!observation) return 'Coach observation not found.';
+  return ` Coach observation ${chalk.bold(observation.id)} feedback is ${chalk.bold(observation.userFeedbackStatus ?? 'unknown')}.`;
+}
+
 // --- Main export ---
 
 export function formatHelp(opts = {}) {
@@ -848,6 +869,9 @@ export function formatHelp(opts = {}) {
     cmd('login --session-file <file>', 'Import session file'),
     cmd('logout', 'Clear session'),
     '',
+    header('AGENT TOKENS'),
+    ...agentCommandSchema.map((c) => cmd(c.usage ?? c.command, c.description)),
+    '',
     header('OTHER'),
     cmd('browse', 'Interactive Ink browser'),
     cmd('tui', 'Alias for browse'),
@@ -891,7 +915,9 @@ export function formatPretty(command, payload) {
     'increment-score-upload': formatIncrementScoreUpload,
     'coach-observations-current': formatCoachObservationsCurrent,
     'coach-observations-seen': formatCoachObservationMutation,
-    'coach-observations-dismiss': formatCoachObservationMutation
+    'coach-observations-dismiss': formatCoachObservationMutation,
+    'coach-observations-outcome': formatCoachObservationOutcomeMutation,
+    'coach-observations-feedback': formatCoachObservationFeedbackMutation
   }[command];
 
   return formatter ? formatter(payload) : null;

package/src/lib.js

@@ -2,14 +2,18 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { spawn, execFileSync } from 'node:child_process';
-import { capabilities, commandSchema, contractVersion, officialCommands, proposalSchema, readCommands, writeCommands, writeCommandSchema } from './contract.js';
+import { accessModel, agentCommandSchema, capabilities, commandSchema, contractVersion, officialCommands, proposalSchema, readCommands, writeCommands, writeCommandSchema } from './contract.js';
 import {
   bootstrapSessionFromRemoteBaseUrl,
+  bootstrapSessionFromRemoteBaseUrlWithAgentToken,
   bootstrapSessionFromRemoteBaseUrlWithDeviceFlow,
   bootstrapSessionFromRemoteBaseUrlWithEmail,
   bootstrapSessionFromSnapshot,
+  createRemoteAgentToken,
   fetchRemoteAuthConfig,
-  importSessionFile
+  importSessionFile,
+  listRemoteAgentTokens,
+  revokeRemoteAgentToken
 } from './auth.js';
 import { clearSessionState, isSessionExpired, readSessionState, resolveConfigDir } from './state.js';
 import { createTransport } from './transport.js';
@@ -19,6 +23,7 @@ import { runBrowseCli } from './browse.js';
 import { ValidationError, validateOptions } from './validate.js';
 import { projectFields } from './fields.js';
 import { buildWriteRequest } from './remote.js';
+import { resolveConfiguredBaseUrl } from './service-url.js';
 
 const schemaById = new Map([
   ...commandSchema.map((c) => [c.id, c]),
@@ -96,7 +101,44 @@ export async function runCli(argv, stdout, stderr) {
     return 0;
   }
 
-  const transport = await createTransport(options, sessionState);
+  let transport;
+  try {
+    transport = await createTransport(options, sessionState);
+  } catch (error) {
+    // `status` is a diagnostic command: if the transport can't be built (e.g. the
+    // refresh endpoint is unreachable), still report local session state plus the
+    // transport error rather than hard-failing. Other commands fail with exit 1.
+    if (normalizedCommand === 'status') {
+      stdout.write(`${JSON.stringify({
+        contractVersion,
+        capabilities,
+        mode: null,
+        config: {
+          dir: resolveConfigDir(),
+          sessionPath: sessionState.path
+        },
+        auth: {
+          loggedIn: Boolean(sessionState.session),
+          sessionExists: sessionState.exists,
+          sessionSchemaVersion: sessionState.session?.version ?? null,
+          expired: isSessionExpired(sessionState.session),
+          error: sessionState.error,
+          account: sessionState.session?.account ?? null,
+          credential: null,
+          authExpired: isSessionExpired(sessionState.session),
+          reauthCommand: 'incremnt login'
+        },
+        transportError: cliErrorPayload(error)
+      }, null, 2)}\n`);
+      return 0;
+    }
+    if (options.json) {
+      stdout.write(`${JSON.stringify(cliErrorPayload(error), null, 2)}\n`);
+    } else {
+      stderr.write(`${error.message}\n`);
+    }
+    return 1;
+  }
 
   if (normalizedCommand === 'status') {
     stdout.write(`${JSON.stringify({
@@ -108,12 +150,26 @@ export async function runCli(argv, stdout, stderr) {
         sessionPath: sessionState.path
       },
       auth: {
-        loggedIn: Boolean(sessionState.session),
+        loggedIn: Boolean(sessionState.session || transport.credential?.source === 'env'),
         sessionExists: sessionState.exists,
         sessionSchemaVersion: sessionState.session?.version ?? null,
-        expired: isSessionExpired(sessionState.session),
+        expired: transport.expired ?? isSessionExpired(sessionState.session),
         error: sessionState.error,
-        account: sessionState.session?.account ?? null
+        account: transport.account ?? sessionState.session?.account ?? null,
+        credential: transport.kind === 'remote'
+          ? {
+              source: transport.credential?.source ?? null,
+              type: transport.credential?.type ?? null,
+              access: transport.credential?.access ?? null,
+              expiresAt: transport.credential?.expiresAt ?? null,
+              canRefresh: transport.credential?.canRefresh ?? false,
+              reauthCommand: transport.credential?.type === 'agent-token'
+                ? 'incremnt login --agent-token <token>'
+                : 'incremnt login'
+            }
+          : null,
+        authExpired: transport.expired ?? isSessionExpired(sessionState.session),
+        reauthCommand: 'incremnt login'
       },
       remote: {
         bootstrap: transport.kind === 'remote' ? transport.bootstrap ?? false : false,
@@ -121,7 +177,8 @@ export async function runCli(argv, stdout, stderr) {
         baseUrl: transport.kind === 'remote' ? transport.baseUrl ?? null : null,
         contractVersion: transport.kind === 'remote' ? transport.contractVersion ?? null : null,
         capabilities: transport.kind === 'remote' ? transport.capabilities ?? null : null,
-        fixturePath: transport.kind === 'remote' ? transport.fixturePath ?? null : null
+        fixturePath: transport.kind === 'remote' ? transport.fixturePath ?? null : null,
+        contractUnchecked: transport.kind === 'remote' ? transport.contractUnchecked ?? false : false
       },
       snapshot: {
         source: transport.snapshotSource?.source ?? null,
@@ -139,6 +196,8 @@ export async function runCli(argv, stdout, stderr) {
       officialCommands,
       schema: commandSchema,
       writeSchema: writeCommandSchema,
+      agentSchema: agentCommandSchema,
+      accessModel,
       proposalSchema
     }, null, 2)}\n`);
     return 0;
@@ -247,6 +306,27 @@ export async function runCli(argv, stdout, stderr) {
     const loginBaseUrl = resolveLoginBaseUrl(options, sessionState);
 
     if (loginBaseUrl) {
+      if (options['agent-token']) {
+        try {
+          const result = await bootstrapSessionFromRemoteBaseUrlWithAgentToken(loginBaseUrl, options['agent-token']);
+          stdout.write(`${JSON.stringify({
+            ok: true,
+            sessionPath: result.path,
+            account: result.session.account,
+            credential: result.session.auth ? {
+              type: result.session.auth.type ?? null,
+              access: result.session.auth.access ?? null
+            } : null,
+            remoteContractVersion: result.session.transport?.contractVersion ?? null,
+            transport: result.session.transport
+          }, null, 2)}\n`);
+          return 0;
+        } catch (error) {
+          stderr.write(`${error.message}\n`);
+          return 1;
+        }
+      }
+
       if (options.token && options.email) {
         stderr.write('Pass either --token or --email with --base-url, not both\n');
         return 1;
@@ -348,6 +428,104 @@ export async function runCli(argv, stdout, stderr) {
     return 1;
   }
 
+  if (normalizedCommand === 'agents create' || normalizedCommand === 'agents list' || normalizedCommand === 'agents revoke') {
+    const currentSessionState = await readSessionState();
+    const currentSession = currentSessionState.session ?? sessionState.session;
+    const baseUrl = options['base-url'] ?? currentSession?.transport?.baseUrl ?? null;
+    const bearerToken = currentSession?.auth?.type === 'agent-token'
+      ? null
+      : currentSession?.auth?.accessToken;
+
+    if (!baseUrl || !bearerToken) {
+      const message = 'Agent token management requires a human login. Run incremnt login first.';
+      if (options.json) {
+        stdout.write(`${JSON.stringify({ error: message, code: 'REMOTE_AUTH_REQUIRED', reauthCommand: 'incremnt login' }, null, 2)}\n`);
+      } else {
+        stderr.write(`${message}\n`);
+      }
+      return 1;
+    }
+
+    try {
+      if (normalizedCommand === 'agents create') {
+        const name = typeof options.name === 'string' ? options.name.trim() : '';
+        if (!name) {
+          throw Object.assign(new Error('--name is required for agents create.'), { code: 'MISSING_OPTION' });
+        }
+        const access = options.access ?? 'read';
+        const expiresDays = options['expires-days'] ?? 90;
+        const payload = await createRemoteAgentToken(baseUrl, bearerToken, {
+          name,
+          access,
+          expiresDays
+        });
+        let stored = null;
+        let warning = null;
+        if (options.store) {
+          try {
+            const storedSession = await bootstrapSessionFromRemoteBaseUrlWithAgentToken(baseUrl, payload.agentToken.token, {
+              access: payload.agentToken.access,
+              expiresAt: payload.agentToken.expiresAt ?? null
+            });
+            stored = {
+              ok: true,
+              sessionPath: storedSession.path,
+              credential: {
+                type: storedSession.session.auth?.type ?? null,
+                access: storedSession.session.auth?.access ?? null
+              }
+            };
+            // --store replaces the active CLI session with this agent token. The
+            // human login that authorised this command is now gone; flag it so the
+            // caller isn't silently demoted (token management needs a human login).
+            warning = 'The active CLI session is now this agent token. Run `incremnt login` to restore your human session (required for agent token management).';
+          } catch (error) {
+            stored = {
+              ok: false,
+              error: error?.message ?? String(error),
+              code: error?.code ?? null
+            };
+            // The token was minted server-side and is shown once below. Do NOT fail
+            // the command — a non-zero exit invites callers to discard stdout and
+            // retry, orphaning a live token. Surface the salvage instruction instead.
+            warning = 'Token was created but could not be stored locally. Capture agentToken.token now — it cannot be retrieved again — and set INCREMNT_AGENT_TOKEN manually.';
+          }
+        }
+        stdout.write(`${JSON.stringify({
+          ...payload,
+          tokenIssued: true,
+          ...(options.store ? { persisted: Boolean(stored?.ok) } : {}),
+          stored,
+          ...(warning ? { warning } : {})
+        }, null, 2)}\n`);
+        // Exit 0: the primary operation (minting the token) succeeded regardless of
+        // local persistence. Persistence failures are reported via `persisted`/`warning`.
+        return 0;
+      }
+
+      if (normalizedCommand === 'agents list') {
+        const payload = await listRemoteAgentTokens(baseUrl, bearerToken);
+        stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+      }
+
+      const id = typeof options.id === 'string' ? options.id.trim() : '';
+      if (!id) {
+        throw Object.assign(new Error('--id is required for agents revoke.'), { code: 'MISSING_OPTION' });
+      }
+      const payload = await revokeRemoteAgentToken(baseUrl, bearerToken, id);
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      return 0;
+    } catch (error) {
+      if (options.json) {
+        stdout.write(`${JSON.stringify(cliErrorPayload(error), null, 2)}\n`);
+      } else {
+        stderr.write(`${error.message}\n`);
+      }
+      return 1;
+    }
+  }
+
   if (normalizedCommand === 'browse') {
     if (!(stdout.isTTY ?? false) || !(process.stdin.isTTY ?? false)) {
       stderr.write('browse requires an interactive TTY.\n');
@@ -403,7 +581,7 @@ export async function runCli(argv, stdout, stderr) {
         return 0;
       } catch (error) {
         if (explicitJson) {
-          stdout.write(`${JSON.stringify({ error: error.message, code: error.code ?? null }, null, 2)}\n`);
+          stdout.write(`${JSON.stringify(cliErrorPayload(error), null, 2)}\n`);
         } else {
           stderr.write(`${error.message}\n`);
         }
@@ -423,7 +601,7 @@ export async function runCli(argv, stdout, stderr) {
       return 0;
     } catch (error) {
       if (explicitJson) {
-        stdout.write(`${JSON.stringify({ error: error.message, code: error.code ?? null }, null, 2)}\n`);
+        stdout.write(`${JSON.stringify(cliErrorPayload(error), null, 2)}\n`);
       } else {
         stderr.write(`${error.message}\n`);
       }
@@ -501,7 +679,7 @@ export async function runCli(argv, stdout, stderr) {
     return 0;
   } catch (error) {
     if (explicitJson) {
-      stdout.write(`${JSON.stringify({ error: error.message, code: error.code ?? null }, null, 2)}\n`);
+      stdout.write(`${JSON.stringify(cliErrorPayload(error), null, 2)}\n`);
     } else {
       stderr.write(`${error.message}\n`);
     }
@@ -510,14 +688,24 @@ export async function runCli(argv, stdout, stderr) {
   }
 }
 
-const DEFAULT_BASE_URL = 'https://incremnt-sync.onrender.com';
-
 function resolveLoginBaseUrl(options, sessionState) {
-  if (options['base-url']) return options['base-url'];
-  // If INCREMNT_BASE_URL is explicitly set (even to empty string), respect it — empty = no URL
-  if ('INCREMNT_BASE_URL' in process.env) return process.env.INCREMNT_BASE_URL || null;
-  if (sessionState.session?.transport?.baseUrl) return sessionState.session.transport.baseUrl;
-  return DEFAULT_BASE_URL;
+  return resolveConfiguredBaseUrl(options, sessionState.session);
+}
+
+function cliErrorPayload(error) {
+  const code = error?.code ?? null;
+  return {
+    error: error?.message ?? String(error),
+    code,
+    ...(code === 'SESSION_EXPIRED' ? { authExpired: true, reauthCommand: 'incremnt login' } : {}),
+    ...(code === 'REMOTE_AUTH_ERROR' ? { reauthCommand: 'incremnt login' } : {}),
+    ...(code === 'SNAPSHOT_NOT_FOUND' ? { reauthCommand: 'incremnt login' } : {}),
+    ...(code === 'INSUFFICIENT_SCOPE' ? {
+      requiredAccess: error?.requiredAccess ?? 'write',
+      requiresHuman: error?.requiresHuman ?? true,
+      remedy: error?.remedy ?? 'A write-capable agent token is required. Minting one needs a human login: run `incremnt login`, then `incremnt agents create --access write`.'
+    } : {})
+  };
 }
 
 function isHeadlessLoginEnvironment(options) {