atris 3.34.0 → 3.35.0

package/lib/mission-runtime-loop.js

@@ -57,7 +57,10 @@ function missionRunIntentFromMessage(message) {
   rest = cadenceFlag.text;
   const noRun = hasBooleanFlag(rest, '--no-run') || hasBooleanFlag(rest, '--no-loop');
   const noComplete = hasBooleanFlag(rest, '--no-complete');
+  const forceRoomPreflight = hasBooleanFlag(rest, '--preflight') || hasBooleanFlag(rest, '--room-preflight');
+  const skipRoomPreflight = hasBooleanFlag(rest, '--no-preflight') || hasBooleanFlag(rest, '--no-room-preflight') || !forceRoomPreflight;
   rest = stripBooleanFlag(stripBooleanFlag(stripBooleanFlag(rest, '--no-run'), '--no-loop'), '--no-complete');
+  rest = stripBooleanFlag(stripBooleanFlag(stripBooleanFlag(stripBooleanFlag(rest, '--preflight'), '--room-preflight'), '--no-preflight'), '--no-room-preflight');
   rest = rest.replace(/(^|\s)--json(?=\s|$)/g, ' ').replace(/\s+/g, ' ').trim();
 
   const wantsLongRun = /\b(24\s*h|24\s*hours?|overnight|forever)\b/i.test(text);
@@ -69,6 +72,8 @@ function missionRunIntentFromMessage(message) {
     cadence: cadenceFlag.value || (wantsLongRun ? '15m' : ''),
     noRun,
     noComplete,
+    roomPreflight: forceRoomPreflight,
+    noRoomPreflight: skipRoomPreflight,
   };
 }
 
@@ -245,6 +250,8 @@ async function runRuntimeMissionLoop(intent, options = {}) {
 
   const startArgs = ['mission', 'run', intent.objective, '--runner', 'atris2', '--owner', intent.owner || 'mission-lead', '--json'];
   if (intent.cadence) startArgs.push('--cadence', intent.cadence);
+  if (intent.roomPreflight) startArgs.push('--room-preflight');
+  else if (intent.noRoomPreflight) startArgs.push('--no-room-preflight');
   const start = runCliJsonSync(cliPath, startArgs, { cwd, timeoutMs: 30000 });
   const result = { ok: start.ok, status: start.status, start, noRun: intent.noRun === true, achieved: false };
   if (!start.ok || !start.payload?.mission?.id) {

package/lib/official-cli-integration.js

@@ -0,0 +1,174 @@
+const { spawnSync } = require('node:child_process');
+
+function hasHelp(args = []) {
+  return args.includes('--help') || args.includes('-h') || args[0] === 'help';
+}
+
+function firstLine(value) {
+  return String(value || '').split(/\r?\n/).map((line) => line.trim()).find(Boolean) || 'unknown';
+}
+
+function formatCommand(parts = []) {
+  return parts.join(' ').trim();
+}
+
+function runCaptured(binary, args = []) {
+  return spawnSync(binary, args, {
+    encoding: 'utf8',
+    env: process.env,
+  });
+}
+
+function missingBinary(result) {
+  return result && result.error && result.error.code === 'ENOENT';
+}
+
+function printMissingBinary(config) {
+  console.error(`${config.name} cli not found.`);
+  console.error(`install: ${config.installHint}`);
+}
+
+function ensureBinary(config) {
+  const result = runCaptured(config.binary, config.versionArgs || ['--version']);
+  if (missingBinary(result)) {
+    printMissingBinary(config);
+    return { ok: false, result };
+  }
+  if (result.error) {
+    console.error(`${config.name} cli check failed: ${result.error.message}`);
+    return { ok: false, result };
+  }
+  return { ok: true, result };
+}
+
+function runAuthCheck(config) {
+  if (!config.authArgs || config.authArgs.length === 0) {
+    return { ok: true, skipped: true };
+  }
+  const result = runCaptured(config.binary, config.authArgs);
+  if (missingBinary(result)) {
+    printMissingBinary(config);
+    return { ok: false, result };
+  }
+  if (result.error) {
+    console.error(`${config.name} auth check failed: ${result.error.message}`);
+    return { ok: false, result };
+  }
+  return { ok: result.status === 0, result };
+}
+
+function printHelp(config) {
+  console.log('');
+  console.log(`usage: atris ${config.name} <command> [args]`);
+  console.log('');
+  console.log('commands:');
+  console.log('  doctor        detect the cli binary and auth state');
+  console.log('  auth          check auth state');
+  for (const command of config.commands) {
+    console.log(`  ${command.usage.padEnd(13)} ${command.description}`);
+  }
+  console.log('');
+  console.log(`binary: ${config.binary}`);
+  console.log(`install: ${config.installHint}`);
+  console.log('');
+}
+
+function printDoctor(config) {
+  const binary = ensureBinary(config);
+  if (!binary.ok) return 1;
+
+  console.log(`${config.name} integration`);
+  console.log(`binary: found ${config.binary}`);
+  console.log(`version: ${firstLine(binary.result.stdout || binary.result.stderr).toLowerCase()}`);
+
+  const auth = runAuthCheck(config);
+  if (auth.skipped) {
+    console.log('auth: not checked');
+    return 0;
+  }
+  if (auth.ok) {
+    console.log('auth: ok');
+    return 0;
+  }
+  console.error('auth: failed');
+  console.error(`login: ${config.loginHint}`);
+  return 1;
+}
+
+function printAuth(config) {
+  const binary = ensureBinary(config);
+  if (!binary.ok) return 1;
+  const auth = runAuthCheck(config);
+  if (auth.skipped || auth.ok) {
+    console.log('auth: ok');
+    return 0;
+  }
+  console.error('auth: failed');
+  console.error(`login: ${config.loginHint}`);
+  return 1;
+}
+
+function matchCommand(config, args) {
+  return config.commands.find((command) => {
+    if (args.length < command.match.length) return false;
+    return command.match.every((part, index) => args[index] === part);
+  });
+}
+
+function runPassthrough(config, command, args) {
+  const binary = ensureBinary(config);
+  if (!binary.ok) return 1;
+
+  const rest = args.slice(command.match.length);
+  const cliArgs = [...command.forward, ...rest];
+  const result = spawnSync(config.binary, cliArgs, {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (missingBinary(result)) {
+    printMissingBinary(config);
+    return 1;
+  }
+  if (result.error) {
+    console.error(`${config.name} command failed: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 0;
+}
+
+function createOfficialCliCommand(config) {
+  return function officialCliCommand(args = []) {
+    const normalizedArgs = Array.isArray(args) ? args : Array.from(arguments);
+    if (normalizedArgs.length === 0 || hasHelp(normalizedArgs)) {
+      printHelp(config);
+      return 0;
+    }
+
+    const subcommand = normalizedArgs[0];
+    const doctorAliases = config.doctorAliases || ['doctor', 'status'];
+    if (doctorAliases.includes(subcommand)) {
+      return printDoctor(config);
+    }
+    if (subcommand === 'auth') {
+      return printAuth(config);
+    }
+
+    const command = matchCommand(config, normalizedArgs);
+    if (!command) {
+      console.error(`unknown ${config.name} command: ${formatCommand(normalizedArgs)}`);
+      console.error(`run: atris ${config.name} --help`);
+      return 1;
+    }
+
+    return runPassthrough(config, command, normalizedArgs);
+  };
+}
+
+module.exports = {
+  createOfficialCliCommand,
+  ensureBinary,
+  hasHelp,
+  matchCommand,
+  printHelp,
+  runAuthCheck,
+};

package/lib/outbound-send-gate.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  HTML_TAG_RE,
+  RENDERED_SOURCE_FENCE_RE,
+  scanOutboundArtifact,
+} = require('../scripts/outbound-artifact-gate');
+
+const DEFAULT_GATE = Object.freeze({
+  format: 'plain',
+  proofFile: null,
+  bodyFile: null,
+  visual: false,
+  allowSlop: false,
+});
+
+class OutboundArtifactGateError extends Error {
+  constructor(check, file, errors = []) {
+    super(`outbound artifact gate failed: ${check} in ${file}`);
+    this.name = 'OutboundArtifactGateError';
+    this.check = check;
+    this.file = file;
+    this.errors = errors;
+  }
+}
+
+function defaultGateOptions() {
+  return { ...DEFAULT_GATE };
+}
+
+function readOutboundBodyFile(bodyFile) {
+  const file = path.resolve(String(bodyFile || ''));
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    throw new OutboundArtifactGateError('body-file-read-error', file);
+  }
+}
+
+function writeInlineBodyFile(body) {
+  const file = path.join(os.tmpdir(), `atris-outbound-gate-${process.pid}-${Date.now()}.txt`);
+  fs.writeFileSync(file, String(body || ''), { encoding: 'utf8', flag: 'wx' });
+  return file;
+}
+
+function normalizeProofFile(proofFile) {
+  return proofFile ? path.resolve(String(proofFile)) : null;
+}
+
+function extractOutboundGateOptions(args = []) {
+  const rest = [];
+  const gate = defaultGateOptions();
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i] || '');
+    const eq = arg.indexOf('=');
+    const key = eq >= 0 ? arg.slice(0, eq) : arg;
+    const inlineValue = eq >= 0 ? arg.slice(eq + 1) : null;
+
+    if (key === '--visual') {
+      gate.visual = true;
+      continue;
+    }
+    if (key === '--allow-slop') {
+      gate.allowSlop = true;
+      continue;
+    }
+    if (key === '--format') {
+      gate.format = String(inlineValue !== null ? inlineValue : args[i + 1] || 'plain').toLowerCase();
+      if (inlineValue === null) i += 1;
+      continue;
+    }
+    if (key === '--proof-file' || key === '--render-proof') {
+      gate.proofFile = normalizeProofFile(inlineValue !== null ? inlineValue : args[i + 1]);
+      if (inlineValue === null) i += 1;
+      continue;
+    }
+    if (key === '--body-file') {
+      gate.bodyFile = path.resolve(String(inlineValue !== null ? inlineValue : args[i + 1] || ''));
+      if (inlineValue === null) i += 1;
+      continue;
+    }
+
+    rest.push(arg);
+  }
+
+  return { args: rest, gate };
+}
+
+function parseOutboundSendArgs(args = []) {
+  const parsed = extractOutboundGateOptions(args);
+  return {
+    text: parsed.gate.bodyFile ? '' : parsed.args.join(' ').trim(),
+    gate: parsed.gate,
+  };
+}
+
+function shouldRunOutboundGate(channel, body, gate = {}) {
+  const format = String(gate.format || 'plain').toLowerCase();
+  if (format !== 'plain') return true;
+  if (gate.visual || gate.proofFile || gate.bodyFile) return true;
+  return HTML_TAG_RE.test(body) || RENDERED_SOURCE_FENCE_RE.test(body);
+}
+
+function assertOutboundSendAllowed(channel, body, gate = {}) {
+  const options = { ...defaultGateOptions(), ...(gate || {}) };
+  options.format = String(options.format || 'plain').toLowerCase();
+  options.channel = String(channel || 'other').toLowerCase();
+  options.proofFile = normalizeProofFile(options.proofFile);
+  if (options.bodyFile) options.bodyFile = path.resolve(String(options.bodyFile));
+
+  const inspectedBody = options.bodyFile ? readOutboundBodyFile(options.bodyFile) : String(body || '');
+  if (!shouldRunOutboundGate(options.channel, inspectedBody, options)) {
+    return { ok: true, inspected: false, body: inspectedBody, file: null };
+  }
+
+  const inspectedFile = options.bodyFile || writeInlineBodyFile(inspectedBody);
+  const errors = scanOutboundArtifact({
+    channel: options.channel,
+    format: options.format,
+    bodyFile: inspectedFile,
+    proofFile: options.proofFile,
+    visual: options.visual,
+    allowSlop: options.allowSlop,
+  }, inspectedBody);
+
+  if (errors.length) {
+    throw new OutboundArtifactGateError(errors[0].id, inspectedFile, errors);
+  }
+
+  return { ok: true, inspected: true, body: inspectedBody, file: inspectedFile };
+}
+
+function exitOutboundGateFailure(error) {
+  console.error(error.message);
+  process.exit(1);
+}
+
+function assertOutboundSendAllowedOrExit(channel, body, gate = {}, options = {}) {
+  try {
+    return assertOutboundSendAllowed(channel, body, gate);
+  } catch (error) {
+    exitOutboundGateFailure(error, options);
+  }
+}
+
+function prepareOutboundSendTextOrExit(channel, args = [], options = {}) {
+  const parsed = parseOutboundSendArgs(args);
+  return assertOutboundSendAllowedOrExit(channel, parsed.text, parsed.gate, options);
+}
+
+module.exports = {
+  OutboundArtifactGateError,
+  assertOutboundSendAllowed,
+  assertOutboundSendAllowedOrExit,
+  defaultGateOptions,
+  extractOutboundGateOptions,
+  parseOutboundSendArgs,
+  prepareOutboundSendTextOrExit,
+  readOutboundBodyFile,
+  shouldRunOutboundGate,
+};

package/lib/permission-grants.js

@@ -0,0 +1,293 @@
+'use strict';
+
+// Persistent permission grants (CLI-831).
+// A grant lets an exact approved command pattern auto-redeem its workspace
+// approval instead of re-asking. syncGrants() pushes the local store to the
+// backend and pulls back grants created or revoked from atrisos-web, so the
+// same grants can be reviewed and revoked from the web.
+// Design brief: atris/designs/permission-grants-cli-831.md
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const GRANTS_SCHEMA = 'atris.permission_grants.v1';
+
+// Backend reconciliation endpoint. The CLI POSTs its local grants and the
+// backend echoes the authoritative set (including web-created/revoked grants).
+const GRANTS_SYNC_ENDPOINT = '/workspace/permission-grants/sync';
+
+// Shell metacharacters change the meaning of a command after matching, so a
+// command containing any of them is never grantable and never matchable.
+const SHELL_META = /[;&|<>`$(){}\[\]*?~\\\n\r]|\r|\n/;
+
+// Commands that must always re-ask, no matter what the operator granted.
+const NEVER_GRANTABLE = [
+  /^sudo\b/,
+  /\brm\s+(-\w*[rf]\w*\s+)+/,
+  /\bgit\s+push\s+.*--force/,
+  /\bgit\s+reset\s+--hard/,
+  /\b(sh|bash|zsh)\s+-c\b/,
+  /\bnode\s+-e\b/,
+  /\bpython3?\s+-c\b/,
+  /\bchmod\b|\bchown\b/,
+  /credentials\.json|\.ssh\b|\.env\b/,
+  /\batris\s+task\s+accept\b/,
+  /\bautoland\b.*polic/,
+];
+
+function grantsFilePath() {
+  return process.env.ATRIS_PERMISSION_GRANTS_FILE
+    || path.join(os.homedir(), '.atris', 'permission-grants.json');
+}
+
+function parseArgv(command) {
+  const text = String(command || '').trim();
+  if (!text || SHELL_META.test(text)) return null;
+  const argv = text.split(/\s+/).filter(Boolean);
+  return argv.length ? argv : null;
+}
+
+function commandIsGrantable(command) {
+  const text = String(command || '').trim();
+  if (!text) return { ok: false, reason: 'empty command' };
+  if (SHELL_META.test(text)) return { ok: false, reason: 'shell metacharacters are never grantable' };
+  for (const rule of NEVER_GRANTABLE) {
+    if (rule.test(text)) return { ok: false, reason: `never grantable: matches ${rule}` };
+  }
+  return { ok: true };
+}
+
+function loadGrants(file = grantsFilePath()) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data && data.schema === GRANTS_SCHEMA && Array.isArray(data.grants)) return data;
+  } catch {
+    // Missing or unreadable store means no grants; fail closed to re-asking.
+  }
+  return { schema: GRANTS_SCHEMA, grants: [] };
+}
+
+function saveGrants(store, file = grantsFilePath()) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function canonicalRoot(workspaceRoot) {
+  try {
+    return fs.realpathSync(String(workspaceRoot || ''));
+  } catch {
+    return String(workspaceRoot || '');
+  }
+}
+
+function addGrant({ command, workspaceRoot, createdVia = 'cli', expiresInDays = 30, file } = {}) {
+  const grantable = commandIsGrantable(command);
+  if (!grantable.ok) return { ok: false, reason: grantable.reason };
+  const argv = parseArgv(command);
+  if (!argv) return { ok: false, reason: 'command does not parse to a plain argv' };
+  const root = canonicalRoot(workspaceRoot);
+  if (!root || root === '/') return { ok: false, reason: 'grants must be scoped to a workspace root' };
+  const store = loadGrants(file);
+  const now = new Date();
+  const grant = {
+    grant_id: `grant-${crypto.randomBytes(6).toString('hex')}`,
+    status: 'active',
+    scope: { kind: 'workspace', workspace_root: root },
+    principal: { created_via: createdVia },
+    action_type: 'local_command',
+    pattern: {
+      type: 'exact_argv',
+      argv,
+      display: argv.join(' '),
+      normalized_hash: crypto.createHash('sha256').update(argv.join(' ')).digest('hex'),
+    },
+    constraints: {
+      expires_at: new Date(now.getTime() + expiresInDays * 24 * 60 * 60 * 1000).toISOString(),
+      cwd_must_be_within_workspace: true,
+    },
+    audit: { created_at: now.toISOString(), last_used_at: null, use_count: 0 },
+  };
+  store.grants.push(grant);
+  saveGrants(store, file);
+  return { ok: true, grant };
+}
+
+function revokeGrant(grantId, file) {
+  const store = loadGrants(file);
+  const grant = store.grants.find(g => g.grant_id === grantId || String(g.grant_id).startsWith(String(grantId)));
+  if (!grant) return { ok: false, reason: 'grant not found' };
+  grant.status = 'revoked';
+  grant.sync = { ...(grant.sync || {}), revoked_at: new Date().toISOString() };
+  saveGrants(store, file);
+  return { ok: true, grant };
+}
+
+function matchGrant({ command, workspaceRoot, now = new Date(), file } = {}) {
+  const argv = parseArgv(command);
+  if (!argv) return null;
+  if (!commandIsGrantable(command).ok) return null;
+  const root = canonicalRoot(workspaceRoot);
+  const store = loadGrants(file);
+  for (const grant of store.grants) {
+    if (grant.status !== 'active') continue;
+    if (grant.action_type !== 'local_command') continue;
+    if (!grant.scope || grant.scope.workspace_root !== root) continue;
+    const expiresAt = grant.constraints && grant.constraints.expires_at;
+    if (expiresAt && new Date(expiresAt).getTime() <= now.getTime()) continue;
+    const maxUses = grant.constraints && grant.constraints.max_uses;
+    if (maxUses && (grant.audit?.use_count || 0) >= maxUses) continue;
+    const pattern = grant.pattern || {};
+    if (pattern.type === 'exact_argv') {
+      if (Array.isArray(pattern.argv)
+        && pattern.argv.length === argv.length
+        && pattern.argv.every((token, i) => token === argv[i])) return grant;
+    } else if (pattern.type === 'argv_prefix') {
+      if (Array.isArray(pattern.argv)
+        && pattern.argv.length <= argv.length
+        && pattern.argv.every((token, i) => token === argv[i])) return grant;
+    }
+  }
+  return null;
+}
+
+function recordUse(grantId, file) {
+  const store = loadGrants(file);
+  const grant = store.grants.find(g => g.grant_id === grantId);
+  if (!grant) return null;
+  grant.audit = grant.audit || {};
+  grant.audit.use_count = (grant.audit.use_count || 0) + 1;
+  grant.audit.last_used_at = new Date().toISOString();
+  saveGrants(store, file);
+  return grant;
+}
+
+// A grant pulled from the backend is only trusted if it would itself have been
+// grantable locally. This is the fail-closed seam for sync: a compromised or
+// buggy backend can never inject an auto-approvable dangerous pattern, because
+// its command must survive the same NEVER_GRANTABLE / metacharacter gate that
+// addGrant() applies. Malformed or non-command grants are dropped.
+function normalizeRemoteGrant(remote) {
+  if (!remote || typeof remote !== 'object') return null;
+  if (String(remote.action_type || '') !== 'local_command') return null;
+  const grantId = String(remote.grant_id || '');
+  if (!grantId) return null;
+  const pattern = remote.pattern || {};
+  const type = pattern.type;
+  if (type !== 'exact_argv' && type !== 'argv_prefix') return null;
+  if (!Array.isArray(pattern.argv) || !pattern.argv.length) return null;
+  if (!pattern.argv.every(token => typeof token === 'string' && token.length)) return null;
+  const display = typeof pattern.display === 'string' && pattern.display
+    ? pattern.display
+    : pattern.argv.join(' ');
+  if (!commandIsGrantable(display).ok) return null;
+  const root = String((remote.scope && remote.scope.workspace_root) || '');
+  if (!root || root === '/') return null;
+  return {
+    grant_id: grantId,
+    status: remote.status === 'revoked' ? 'revoked' : 'active',
+    scope: { kind: 'workspace', workspace_root: root },
+    principal: (remote.principal && typeof remote.principal === 'object')
+      ? remote.principal
+      : { created_via: 'web' },
+    action_type: 'local_command',
+    pattern: {
+      type,
+      argv: pattern.argv.slice(),
+      display,
+      normalized_hash: crypto.createHash('sha256').update(pattern.argv.join(' ')).digest('hex'),
+    },
+    constraints: (remote.constraints && typeof remote.constraints === 'object')
+      ? remote.constraints
+      : {},
+    audit: (remote.audit && typeof remote.audit === 'object')
+      ? remote.audit
+      : { created_at: null, last_used_at: null, use_count: 0 },
+    sync: (remote.sync && typeof remote.sync === 'object')
+      ? remote.sync
+      : { source: 'web' },
+  };
+}
+
+// Merge the backend's authoritative grants into the local store in place.
+// - New grants (created/managed from web) are pulled down so the CLI can redeem
+//   them locally.
+// - Revocation always wins: a grant revoked on the web is revoked locally, and a
+//   grant we already revoked is never resurrected. Permission state fails closed.
+function mergeRemoteGrants(store, remoteGrants = [], now = new Date()) {
+  const byId = new Map(store.grants.map(g => [g.grant_id, g]));
+  let pulled = 0;
+  let revoked = 0;
+  let rejected = 0;
+  for (const raw of Array.isArray(remoteGrants) ? remoteGrants : []) {
+    const remote = normalizeRemoteGrant(raw);
+    if (!remote) { rejected += 1; continue; }
+    const local = byId.get(remote.grant_id);
+    if (!local) {
+      store.grants.push(remote);
+      byId.set(remote.grant_id, remote);
+      if (remote.status === 'revoked') revoked += 1;
+      else pulled += 1;
+      continue;
+    }
+    if (remote.status === 'revoked' && local.status !== 'revoked') {
+      local.status = 'revoked';
+      local.sync = {
+        ...(local.sync || {}),
+        revoked_at: (remote.sync && remote.sync.revoked_at) || now.toISOString(),
+        revoked_by: 'web',
+      };
+      revoked += 1;
+    }
+  }
+  return { pulled, revoked, rejected };
+}
+
+// Push the local grants to the backend and merge back the authoritative set.
+// apiRequestJson is injected (utils/api) so this stays offline-testable. The
+// call is best-effort: on any transport/HTTP failure the local store is left
+// untouched and { ok: false, reason } is returned — grants keep working locally.
+async function syncGrants({ apiRequestJson, token, file, endpoint = GRANTS_SYNC_ENDPOINT, now = new Date() } = {}) {
+  if (typeof apiRequestJson !== 'function') {
+    return { ok: false, reason: 'no api client' };
+  }
+  const store = loadGrants(file);
+  let response;
+  try {
+    response = await apiRequestJson(endpoint, {
+      method: 'POST',
+      token,
+      body: { schema: GRANTS_SCHEMA, grants: store.grants },
+    });
+  } catch (error) {
+    return { ok: false, reason: (error && error.message) || 'sync request failed', pushed: store.grants.length };
+  }
+  if (!response || !response.ok) {
+    return { ok: false, reason: (response && response.error) || 'sync request failed', pushed: store.grants.length };
+  }
+  const remoteGrants = (response.data && Array.isArray(response.data.grants)) ? response.data.grants : [];
+  const merged = mergeRemoteGrants(store, remoteGrants, now);
+  saveGrants(store, file);
+  return { ok: true, pushed: store.grants.length, ...merged };
+}
+
+module.exports = {
+  GRANTS_SCHEMA,
+  GRANTS_SYNC_ENDPOINT,
+  grantsFilePath,
+  parseArgv,
+  commandIsGrantable,
+  loadGrants,
+  saveGrants,
+  addGrant,
+  revokeGrant,
+  matchGrant,
+  recordUse,
+  normalizeRemoteGrant,
+  mergeRemoteGrants,
+  syncGrants,
+};