@anhlp/alp-core 0.0.0-beta.1

package/src/log.js

@@ -0,0 +1,177 @@
+import { open, stat } from 'node:fs/promises';
+
+/**
+ * Structured, redacted logging for ALP processes. One JSON object per line, written to stderr
+ * unless a sink is given: stdout belongs to command output, `--json` and the ACP stream, so a
+ * log line never lands there. A record has `time`, `level`, `component`, an optional error
+ * `code`, `msg`, correlation ids (`sessionId`, `rootId`, `assignmentId`, `clientMessageId`,
+ * `requestId`, `agent`) and a few extra fields. Logging never throws.
+ *
+ * Nothing sensitive is logged by default: keys that carry prompts, environments or credentials
+ * are replaced, secret-looking values and the values of secret-named environment variables are
+ * scrubbed from every string, and long strings are cut.
+ */
+
+export const LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
+export const REDACTED = '[redacted]';
+export const OMITTED = '[omitted]';
+const MAX_STRING = 2000;
+const MAX_DEPTH = 5;
+const MAX_KEYS = 50;
+const MAX_ITEMS = 20;
+const STACK_LINES = 8;
+
+/** Fields that hold a credential: the value is replaced. */
+const SECRET_KEY = /pass(word|wd)?|secret|token|api[-_]?key|authorization|credential|cookie|private[-_]?key|bearer|signature/i;
+/** Fields that hold user content or the process environment: never logged, not even scrubbed. */
+const OMITTED_KEY = /^(env|environment|prompt|prompts|instructions|content|text|input|headers|body|args|argv)$/i;
+/** Environment variable names whose values are secrets, to find them inside any text. */
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|PRIVATE/i;
+
+const PATTERNS = [
+  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`],
+  [/\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}/g, REDACTED],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, REDACTED],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, REDACTED],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, REDACTED],
+  [/\bAKIA[0-9A-Z]{16}\b/g, REDACTED],
+  [/\bAIza[0-9A-Za-z_-]{30,}/g, REDACTED],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, REDACTED],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(-----END [A-Z ]*PRIVATE KEY-----|$)/g, REDACTED],
+  [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REDACTED}@`],
+  // NAME=value and NAME: value for names that look like secrets; also JSON "token": "value".
+  [/(\b[\w.-]*(?:key|token|secret|passw(?:or)?d|credential|authorization|cookie)[\w.-]*["']?\s*[=:]\s*)(?:"[^"]{4,}"|'[^']{4,}'|[^\s,;&"']{8,})/gi, `$1${REDACTED}`],
+  // --token value, --api-key value
+  [/(--[\w-]*(?:key|token|secret|passw(?:or)?d|credential)[\w-]*\s+)[^\s-][^\s]*/gi, `$1${REDACTED}`],
+];
+
+/** Values of secret-named variables in `env`, long enough that replacing them is not noise. */
+function secretValues(env) {
+  const values = new Set();
+  for (const [name, value] of Object.entries(env ?? {})) if (typeof value === 'string' && value.length >= 8 && SECRET_NAME.test(name)) values.add(value);
+  return [...values].sort((a, b) => b.length - a.length);
+}
+
+/** `text` without anything that looks like a credential, cut to `max` characters. */
+export function scrubText(text, { env = process.env, max = MAX_STRING } = {}) {
+  let result = String(text);
+  for (const value of secretValues(env)) result = result.split(value).join(REDACTED);
+  for (const [pattern, replacement] of PATTERNS) result = result.replace(pattern, replacement);
+  return result.length > max ? `${result.slice(0, max)}... (${result.length - max} more characters)` : result;
+}
+
+/** An error as a plain, scrubbed object: name, code, message and the top of its stack. */
+export function describeError(error, options = {}) {
+  if (!(error instanceof Error)) return { message: scrubText(error, options) };
+  const stack = typeof error.stack === 'string' ? error.stack.split('\n').slice(0, STACK_LINES).join('\n') : undefined;
+  return {
+    name: error.name,
+    ...(typeof error.code === 'string' || typeof error.code === 'number' ? { code: error.code } : {}),
+    message: scrubText(error.message, options),
+    ...(stack ? { stack: scrubText(stack, options) } : {}),
+    ...(error.cause !== undefined ? { cause: describeError(error.cause, options) } : {}),
+  };
+}
+
+/** A copy of `value` that is safe to write to a log: see the module comment. */
+export function redact(value, options = {}, depth = 0, seen = new WeakSet()) {
+  if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number') return value;
+  if (typeof value === 'string') return scrubText(value, options);
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value !== 'object') return undefined;
+  if (value instanceof Error) return describeError(value, options);
+  if (seen.has(value)) return '[circular]';
+  if (depth >= MAX_DEPTH) return '[too deep]';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ITEMS).map(item => redact(item, options, depth + 1, seen));
+    return value.length > MAX_ITEMS ? [...items, `... ${value.length - MAX_ITEMS} more`] : items;
+  }
+  const result = {};
+  for (const [key, item] of Object.entries(value).slice(0, MAX_KEYS)) {
+    result[key] = OMITTED_KEY.test(key) ? OMITTED : SECRET_KEY.test(key) ? REDACTED : redact(item, options, depth + 1, seen);
+  }
+  return result;
+}
+
+/** Fields every record may carry to tie its lines to a session, assignment or request. */
+const CORRELATION = ['sessionId', 'rootId', 'assignmentId', 'clientMessageId', 'requestId', 'agent'];
+
+const stderrSink = line => { try { process.stderr.write(`${line}\n`); } catch {} };
+
+/**
+ * A logger for `component` (`alpd`, `store`, `runtime`, `acp`, ...). `level` defaults to
+ * ALP_LOG_LEVEL, then `info`. `context` ids are added to every record. `write` receives one
+ * serialized line without its newline.
+ */
+export function createLogger({ component, level, context = {}, write = stderrSink, now = () => new Date(), env = process.env } = {}) {
+  const threshold = LEVELS[level ?? env.ALP_LOG_LEVEL] ?? LEVELS.info;
+  const options = { env };
+  const emit = (name, message, fields = {}) => {
+    if (LEVELS[name] < threshold) return;
+    try {
+      const { code, error, ...rest } = { ...context, ...fields };
+      const record = {
+        time: now().toISOString(), level: name, component, ...(code ? { code: String(code) } : {}), msg: scrubText(message, options),
+      };
+      for (const key of CORRELATION) if (rest[key] !== undefined) record[key] = redact(String(rest[key]), options);
+      if (error !== undefined) {
+        record.error = describeError(error, options);
+        // An error's own code names the failure when the caller gave none.
+        if (!record.code && record.error.code !== undefined) record.code = String(record.error.code);
+      }
+      for (const [key, value] of Object.entries(rest)) {
+        if (CORRELATION.includes(key)) continue;
+        record[key] = OMITTED_KEY.test(key) ? OMITTED : SECRET_KEY.test(key) ? REDACTED : redact(value, options);
+      }
+      write(JSON.stringify(record));
+    } catch {}
+  };
+  return {
+    component,
+    debug: (message, fields) => emit('debug', message, fields),
+    info: (message, fields) => emit('info', message, fields),
+    warn: (message, fields) => emit('warn', message, fields),
+    error: (message, fields) => emit('error', message, fields),
+    child: (extra = {}, name = component) => createLogger({ component: name, level, context: { ...context, ...extra }, write, now, env }),
+  };
+}
+
+const TAIL_BYTES = 256 * 1024;
+
+/**
+ * The records at the end of a log file, oldest first. Lines that are not ALP records (output
+ * from before structured logging, a runtime's own stderr) are returned as `{ legacy: text }`
+ * with the text scrubbed. A file that is missing gives an empty list.
+ */
+export async function readLogTail(file, { bytes = TAIL_BYTES, env = process.env } = {}) {
+  let handle;
+  try {
+    handle = await open(file, 'r');
+    const { size } = await stat(file);
+    const start = Math.max(0, size - bytes);
+    const buffer = Buffer.alloc(size - start);
+    await handle.read(buffer, 0, buffer.length, start);
+    const lines = buffer.toString('utf8').split('\n');
+    // The first line of a tail may be cut.
+    if (start > 0) lines.shift();
+    const records = [];
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const record = JSON.parse(line);
+        if (record && typeof record === 'object' && typeof record.time === 'string' && typeof record.level === 'string' && typeof record.msg === 'string') {
+          records.push(redact(record, { env }));
+          continue;
+        }
+      } catch {}
+      records.push({ legacy: scrubText(line, { env, max: 500 }) });
+    }
+    return records;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}

package/src/migrations.d.ts

@@ -0,0 +1,9 @@
+export type Migration = { from: number; to: number; name: string; run(home: string): Promise<void> };
+export const MIGRATIONS: Migration[];
+export type MigrationResult = { from: number; to: number; steps: Array<{ name: string; from: number; to: number; backup: string; resumed: boolean }> };
+export function migrateState(home: string, options?: {
+  by?: string;
+  migrations?: Migration[];
+  target?: number;
+  log?: { info(message: string, fields?: object): void; warn(message: string, fields?: object): void };
+}): Promise<MigrationResult>;

package/src/migrations.js

@@ -0,0 +1,111 @@
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { writeAtomic } from './atomic.js';
+import { STATE_SCHEMA, assertStateSupported, migrationFile, readStateSchema, stateDir, writeStateSchema } from './state-schema.js';
+import { STATE_UNITS, automaticBackup, restoreBackup } from './backup.js';
+
+/**
+ * Versioned migrations of alpd's state (plans/reference/ALPD.md §68). Each step moves the
+ * state from one schema to the next and is idempotent: run again over its own partial or
+ * complete result it writes the same files. Before a step, the state is saved to a backup
+ * and `state/migration.json` names it. Policy:
+ *
+ * - interrupted (a crash, a kill, a power cut): the next start finds the journal and runs
+ *   the step again over what it left, with the same backup;
+ * - failed (the step threw): the state is restored from that backup, the journal removed,
+ *   and the start fails with STATE_MIGRATION_FAILED; the backup stays.
+ *
+ * The schema marker is written only after a step completed, and the journal removed last.
+ */
+
+/**
+ * Schema 1 → 2: every timeline line gets the cursor the store already gives it when reading
+ * (a line without a larger cursor than the line before is numbered one past it). Lines that
+ * do not parse are kept as they are; the store skips them, as before.
+ */
+async function timelineCursors(home) {
+  const directory = path.join(stateDir(home), 'timeline');
+  const names = await readdir(directory).catch(error => { if (error?.code === 'ENOENT') return []; throw error; });
+  for (const name of names.filter(name => name.endsWith('.jsonl'))) {
+    const file = path.join(directory, name);
+    const lines = [];
+    let cursor = 0;
+    let changed = false;
+    for (const line of (await readFile(file, 'utf8')).split('\n')) {
+      if (!line) continue;
+      let envelope;
+      try { envelope = JSON.parse(line); } catch { lines.push(line); continue; }
+      cursor = typeof envelope?.cursor === 'number' && envelope.cursor > cursor ? envelope.cursor : cursor + 1;
+      if (envelope?.cursor === cursor) { lines.push(line); continue; }
+      lines.push(JSON.stringify({ ...envelope, cursor }));
+      changed = true;
+    }
+    if (changed) await writeAtomic(file, lines.map(line => `${line}\n`).join(''));
+  }
+}
+
+/** @type {Array<{ from: number, to: number, name: string, run(home: string): Promise<void> }>} */
+export const MIGRATIONS = [
+  { from: 1, to: 2, name: 'timeline-cursors', run: timelineCursors },
+];
+
+async function readJournal(home) {
+  try { return JSON.parse(await readFile(migrationFile(home), 'utf8')); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    // A journal cut short says only that a migration was under way: start the step over.
+    return {};
+  }
+}
+
+const exists = file => stat(file).then(() => true, () => false);
+
+/**
+ * Brings the state to `target` (the current schema), or refuses a newer one without touching it.
+ * Returns the steps it ran; `resumed` marks a step an interruption had left unfinished.
+ * @param {string} home
+ * @param {{ by?: string, migrations?: typeof MIGRATIONS, target?: number, log?: { info(message: string, fields?: object): void, warn(message: string, fields?: object): void } }} [options]
+ */
+export async function migrateState(home, { by = 'alp', migrations = MIGRATIONS, target = STATE_SCHEMA, log } = {}) {
+  const info = assertStateSupported(await readStateSchema(home), home);
+  let journal = await readJournal(home);
+  if (journal && Number.isSafeInteger(journal.to) && journal.to <= info.schema) {
+    // The step completed and only the journal's removal was cut off.
+    await rm(migrationFile(home), { force: true });
+    journal = undefined;
+  }
+  if (info.fresh && !journal) {
+    await writeStateSchema(home, target, by);
+    return { from: target, to: target, steps: [] };
+  }
+  let schema = info.schema;
+  const steps = [];
+  while (schema < target) {
+    const step = migrations.find(candidate => candidate.from === schema);
+    if (!step) throw new AlpError('STATE_MIGRATION_MISSING', `ALP has no migration from state schema ${schema}; the state was not changed`);
+    const resumed = journal?.to === step.to && typeof journal.backup === 'string' && await exists(journal.backup);
+    const backup = resumed ? journal.backup : await automaticBackup(home, `pre-migrate-v${step.from}-v${step.to}`, { units: STATE_UNITS, by });
+    if (!resumed) await writeAtomic(migrationFile(home), JSON.stringify({ from: step.from, to: step.to, name: step.name, backup, by, startedAt: new Date().toISOString() }) + '\n');
+    log?.info(`${resumed ? 'continuing' : 'running'} state migration ${step.name} (schema ${step.from} → ${step.to}); backup ${backup}`, { code: 'ALP_STATE_MIGRATING', from: step.from, to: step.to, migration: step.name, resumed });
+    try {
+      await step.run(home);
+    } catch (error) {
+      try {
+        await restoreBackup({ home, file: backup, projects: false, safety: false, clearLive: false, by });
+      } catch (rollback) {
+        // The journal stays: the next start runs the step again over what is there.
+        throw new AlpError('STATE_MIGRATION_ROLLBACK_FAILED', `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
+      }
+      await rm(migrationFile(home), { force: true });
+      throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
+    }
+    await writeStateSchema(home, step.to, by);
+    await rm(migrationFile(home), { force: true });
+    steps.push({ name: step.name, from: step.from, to: step.to, backup, resumed });
+    schema = step.to;
+    journal = undefined;
+  }
+  if (!info.marked && !steps.length) await writeStateSchema(home, schema, by);
+  return { from: info.schema, to: schema, steps };
+}

package/src/models.js

@@ -0,0 +1,45 @@
+/** Models ALP offers, with the efforts each takes: the runtime's catalog and alp setup read this list. */
+const codexFull = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const codexStandard = ['low', 'medium', 'high', 'xhigh', 'max'];
+const claudeFull = ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
+const claudeLegacy = ['off', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
+const claude46 = ['off', 'low', 'medium', 'high', 'max'];
+
+/**
+ * @type {Array<{ runtime: 'codex' | 'claude' | 'antigravity', id: string, label: string, description: string, efforts: string[], effort?: string }>}
+ */
+export const MODELS = [
+  ['codex', 'gpt-6.1-sol', 'GPT-6.1-Sol', 'Latest workhorse model for coding and everyday work.', codexFull, 'low'],
+  // ALP runs GPT-6 Astra at low effort only.
+  ['codex', 'gpt-6-astra', 'GPT-6-Astra', 'Frontier intelligence for the most demanding work.', ['low'], 'low'],
+  ['codex', 'gpt-6-sol', 'GPT-6-Sol', 'Previous generation workhorse model.', codexFull, 'low'],
+  ['codex', 'gpt-6-luna', 'GPT-6-Luna', 'Fast and affordable model for easier tasks.', codexStandard, 'low'],
+  ['codex', 'gpt-5.6-sol', 'GPT-5.6-Sol', 'Older generation workhorse model.', codexFull, 'low'],
+  ['codex', 'gpt-5.6-terra', 'GPT-5.6-Terra', 'Older balanced model for straightforward work.', codexFull, 'low'],
+  ['codex', 'gpt-5.6-luna', 'GPT-5.6-Luna', 'Older fast and efficient model.', codexStandard, 'low'],
+  ['claude', 'claude-opus-5-5', 'Opus 5.5', 'Latest release.', claudeFull, 'medium'],
+  ['claude', 'claude-opus-5', 'Opus 5', 'Previous release.', claudeLegacy, 'high'],
+  ['claude', 'claude-fable-5-1', 'Fable 5.1', 'Most powerful model.', claudeFull, 'high'],
+  ['claude', 'claude-fable-5', 'Fable 5', 'Previous release.', claudeFull, 'high'],
+  ['claude', 'claude-opus-4-8[1m]', 'Opus 4.8 1M', 'Opus 4.8 with 1M context window.', claudeLegacy, 'high'],
+  ['claude', 'claude-opus-4-8', 'Opus 4.8', 'Previous release.', claudeLegacy, 'high'],
+  ['claude', 'claude-sonnet-5-5', 'Sonnet 5.5', 'Best for everyday tasks.', claudeFull, 'medium'],
+  ['claude', 'claude-sonnet-5', 'Sonnet 5', 'Previous release.', claudeLegacy, 'high'],
+  ['claude', 'claude-sonnet-5[1m]', 'Sonnet 5 1M', 'Sonnet 5 with 1M context window.', claudeLegacy, 'high'],
+  ['claude', 'claude-opus-4-7[1m]', 'Opus 4.7 1M', 'Opus 4.7 with 1M context window.', claudeLegacy, 'high'],
+  ['claude', 'claude-opus-4-7', 'Opus 4.7', 'Previous release.', claudeLegacy, 'high'],
+  ['claude', 'claude-opus-4-6[1m]', 'Opus 4.6 1M', 'Opus 4.6 with 1M context window.', claude46, 'high'],
+  ['claude', 'claude-opus-4-6', 'Opus 4.6', 'Most capable for complex work.', claude46, 'high'],
+  ['claude', 'claude-sonnet-4-6[1m]', 'Sonnet 4.6 1M', 'Sonnet 4.6 with 1M context window.', claude46, 'high'],
+  ['claude', 'claude-sonnet-4-6', 'Sonnet 4.6', 'Best for everyday tasks.', claude46, 'high'],
+  ['claude', 'claude-haiku-4-5', 'Haiku 4.5', 'Fastest for quick answers.', [], undefined],
+  ['claude', 'sonnet', 'sonnet', 'From Claude settings.json model.', [], undefined],
+  ['antigravity', 'gemini-3.8-flash-high', 'Gemini 3.8 Flash (High)', 'High reasoning effort workhorse for complex tasks.', [], undefined],
+  ['antigravity', 'gemini-3.8-flash-medium', 'Gemini 3.8 Flash (Medium)', 'Balanced speed and reasoning.', [], undefined],
+  ['antigravity', 'gemini-3.8-flash-low', 'Gemini 3.8 Flash (Low)', 'Fast and efficient for straightforward work.', [], undefined],
+  ['antigravity', 'gemini-2.5-pro', 'Gemini 2.5 Pro', 'Deep reasoning for coding and analysis.', [], undefined],
+  ['antigravity', 'gemini-2.5-flash', 'Gemini 2.5 Flash', 'Fast and versatile everyday model.', [], undefined],
+  ['antigravity', 'claude-sonnet-4-6', 'Claude Sonnet 4.6', 'Sonnet 4.6 via Antigravity.', [], undefined],
+  ['antigravity', 'claude-opus-4-6-thinking', 'Claude Opus 4.6 Thinking', 'Opus 4.6 with thinking via Antigravity.', [], undefined],
+  ['antigravity', 'gpt-oss-120b-medium', 'GPT-OSS 120B (Medium)', 'Open weights model via Antigravity.', [], undefined],
+].map(([runtime, id, label, description, efforts, effort]) => ({ runtime, id, label, description, efforts, ...(effort ? { effort } : {}) }));

package/src/permissions.d.ts

@@ -0,0 +1,14 @@
+export type PermissionBase = 'read-only' | 'workspace-write' | 'full-access';
+export type PermissionProfile = { name: string; base: PermissionBase; allow: string[]; ask: string[]; deny: string[]; beyondMode: 'refuse' | 'ask'; workdir?: 'copy' };
+export const BASES: PermissionBase[];
+export const ADVISORS: string[];
+export const MAX_RULES: number;
+export const TOOLS: string[];
+export function parseRule(rule: unknown, source?: string): { tool: string; specifier?: string };
+export function validatePermissions(value: unknown, source: string): { profiles: Record<string, { base?: PermissionBase; beyondMode?: 'refuse' | 'ask'; workdir?: 'copy'; allow: string[]; ask: string[]; deny: string[] }>; agents: Record<string, string> };
+export function addAllowRule(projectRoot: string, home: string | undefined, profileName: string, rule: string): Promise<string>;
+export function profileFor(projectRoot: string, home: string | undefined, agent: string): Promise<PermissionProfile | null>;
+export function capMode(mode: string, base: string): string;
+export function unwrapShell(command: string): string;
+export function simpleCommands(line: string): string[] | null;
+export function commandDecision(profile: Pick<PermissionProfile, 'allow' | 'deny'> & { ask?: string[] }, command: string): 'allow' | 'ask' | 'deny' | undefined;

package/src/permissions.js

@@ -0,0 +1,242 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { moveFile } from './atomic.js';
+import { AlpError } from './errors.js';
+
+/**
+ * Permission profiles: what an agent may do beyond, or never do within, its
+ * base mode. Rules use Claude Code's syntax, `Tool` or `Tool(specifier)`, such as
+ * `Bash(npm test:*)` (a command prefix), `Bash(git status)` (one exact command),
+ * `Edit(src/**)` or `WebFetch(domain:example.com)`.
+ *
+ * Profiles and the agents they apply to come from `permissions` in the project's
+ * .alp/settings.json and the user's $ALP_HOME/settings.json. A profile defined in
+ * both takes its base from the project and the rules of both. An agent's entry in
+ * the project wins over the user's. Deny wins over ask, and ask over allow: an ask
+ * rule makes ALP ask the user every time. With `beyondMode: "ask"`, what the mode
+ * refuses and no rule covers is asked too, and the user may allow it always.
+ *
+ * ALP enforces rules natively where it can: Claude receives them as its own
+ * allowed and disallowed tools, which hold in every permission mode. Codex runs
+ * commands inside its sandbox without asking, so for Codex an allow rule lets a
+ * command leave the sandbox when Codex asks to, and a deny rule refuses that.
+ */
+
+export const BASES = ['read-only', 'workspace-write', 'full-access'];
+const RANK = { 'read-only': 0, 'workspace-write': 1, 'full-access': 2 };
+/** Agents that advise, review or watch: their profiles stay read-only. */
+export const ADVISORS = ['oracle', 'reviewer', 'supervisor'];
+export const MAX_RULES = 200;
+const NAME = /^[\w.-]{1,64}$/;
+const RULE = /^([A-Za-z][\w-]*)(?:\((.*)\))?$/s;
+/** Tools a rule may name; a misspelt one would silently match nothing. MCP tools are mcp__<server>__<tool>. */
+export const TOOLS = ['Bash', 'Read', 'Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Glob', 'Grep', 'WebFetch', 'WebSearch', 'Skill'];
+
+const own = (value, key) => Object.hasOwn(value, key) ? value[key] : undefined;
+const setOwn = (value, key, entry) => Object.defineProperty(value, key, { value: entry, enumerable: true, writable: true, configurable: true });
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (source, message) => { throw new AlpError('INVALID_SETTINGS', `${source}: ${message}`); };
+
+/** Parses one rule; returns { tool, specifier? } or throws. */
+export function parseRule(rule, source = 'rule') {
+  if (typeof rule !== 'string' || rule.length > 500) fail(source, 'a rule is text of at most 500 characters');
+  const match = RULE.exec(rule.trim());
+  if (!match) fail(source, `${JSON.stringify(rule)} is not Tool or Tool(specifier)`);
+  const [, tool, specifier] = match;
+  if (!TOOLS.includes(tool) && !/^mcp__[\w-]+(__[\w-]+)?$/.test(tool)) fail(source, `${JSON.stringify(rule)} names unknown tool ${tool}; use ${TOOLS.join(', ')} or mcp__<server>__<tool>`);
+  if (specifier !== undefined && !specifier.trim()) fail(source, `${JSON.stringify(rule)} has an empty specifier`);
+  return { tool, ...(specifier !== undefined && specifier.trim() !== '*' ? { specifier: specifier.trim() } : {}) };
+}
+
+/** Checks the `permissions` field of a settings file. */
+export function validatePermissions(value, source) {
+  if (value === undefined) return { profiles: {}, agents: {} };
+  if (!object(value)) fail(source, 'permissions must be an object');
+  for (const key of Object.keys(value)) if (!['profiles', 'agents'].includes(key)) fail(source, `unsupported permissions field '${key}'`);
+  const profiles = {};
+  if (value.profiles !== undefined) {
+    if (!object(value.profiles)) fail(source, 'permissions.profiles must be an object');
+    for (const [name, profile] of Object.entries(value.profiles)) {
+      const where = `permissions.profiles.${name}`;
+      if (!NAME.test(name)) fail(source, `${where}: a profile name has letters, digits, dots, dashes and underscores`);
+      if (!object(profile)) fail(source, `${where} must be an object`);
+      for (const key of Object.keys(profile)) if (!['base', 'allow', 'ask', 'deny', 'beyondMode', 'workdir'].includes(key)) fail(source, `${where}: unsupported field '${key}'`);
+      if (profile.workdir !== undefined && profile.workdir !== 'copy') fail(source, `${where}.workdir must be copy`);
+      if (profile.workdir === 'copy' && profile.base !== undefined && profile.base !== 'read-only') fail(source, `${where}: workdir copy is for read-only profiles; writers use worktree isolation`);
+      if (profile.base !== undefined && !BASES.includes(profile.base)) fail(source, `${where}.base must be ${BASES.join(', ')}`);
+      if (profile.beyondMode !== undefined && !['refuse', 'ask'].includes(profile.beyondMode)) fail(source, `${where}.beyondMode must be refuse or ask`);
+      const rules = {};
+      for (const kind of ['allow', 'ask', 'deny']) {
+        const list = profile[kind] ?? [];
+        if (!Array.isArray(list) || list.length > MAX_RULES) fail(source, `${where}.${kind} must list at most ${MAX_RULES} rules`);
+        for (const rule of list) parseRule(rule, `${source}: ${where}.${kind}`);
+        rules[kind] = list.map(rule => rule.trim());
+      }
+      setOwn(profiles, name, { ...(profile.base ? { base: profile.base } : {}), ...(profile.beyondMode ? { beyondMode: profile.beyondMode } : {}), ...(profile.workdir ? { workdir: profile.workdir } : {}), ...rules });
+    }
+  }
+  const agents = {};
+  if (value.agents !== undefined) {
+    if (!object(value.agents)) fail(source, 'permissions.agents must be an object');
+    for (const [agent, profile] of Object.entries(value.agents)) {
+      if (typeof profile !== 'string' || !NAME.test(profile)) fail(source, `permissions.agents.${agent} must name a profile`);
+      setOwn(agents, agent, profile);
+    }
+  }
+  return { profiles, agents };
+}
+
+async function settingsPermissions(file) {
+  let text;
+  try { text = await readFile(file, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return { profiles: {}, agents: {} }; throw error; }
+  let settings;
+  try { settings = JSON.parse(text); } catch (error) { fail(file, `invalid JSON: ${error.message}`); }
+  if (!object(settings)) fail(file, 'expected an object');
+  return validatePermissions(settings.permissions, file);
+}
+
+/**
+ * The permission profile of an agent, or null when none applies: then the agent
+ * keeps the runtime's defaults. Advisors without a profile get a read-only one.
+ * `workdir: 'copy'` runs the agent in a disposable copy of its requester's tree,
+ * where it may write, build and test; the requester's tree stays untouched.
+ * @returns {Promise<{ name: string, base: string, allow: string[], ask: string[], deny: string[], beyondMode: 'refuse' | 'ask', workdir?: 'copy' } | null>}
+ */
+export async function profileFor(projectRoot, home, agent) {
+  const project = await settingsPermissions(path.join(projectRoot, '.alp', 'settings.json'));
+  const user = home ? await settingsPermissions(path.join(home, 'settings.json')) : { profiles: {}, agents: {} };
+  const name = own(project.agents, agent) ?? own(user.agents, agent);
+  const advisor = ADVISORS.includes(agent);
+  if (!name) return advisor ? { name: 'read-only', base: 'read-only', allow: [], ask: [], deny: [], beyondMode: 'refuse' } : null;
+  const defined = [own(project.profiles, name), own(user.profiles, name)].filter(Boolean);
+  if (!defined.length && !BASES.includes(name)) {
+    throw new AlpError('INVALID_SETTINGS', `permissions.agents.${agent} names profile '${name}', which no settings file defines`);
+  }
+  // A bare base name is a profile with no rules.
+  const base = defined.find(profile => profile.base)?.base ?? (BASES.includes(name) ? name : advisor ? 'read-only' : 'full-access');
+  const copy = defined.some(profile => profile.workdir === 'copy');
+  if (copy && base !== 'read-only') throw new AlpError('INVALID_SETTINGS', `Profile '${name}' has workdir copy, which needs base read-only`);
+  if (advisor && base !== 'read-only') throw new AlpError('INVALID_SETTINGS', `${agent} is an advisor; its profile '${name}' must have base read-only`);
+  return {
+    name, base,
+    allow: [...new Set(defined.flatMap(profile => profile.allow ?? []))],
+    ask: [...new Set(defined.flatMap(profile => profile.ask ?? []))],
+    deny: [...new Set(defined.flatMap(profile => profile.deny ?? []))],
+    beyondMode: defined.find(profile => profile.beyondMode)?.beyondMode ?? 'refuse',
+    ...(copy ? { workdir: 'copy' } : {}),
+  };
+}
+
+/**
+ * Adds an allow rule to a profile, in the settings file that defines it (the
+ * project's first), when the user allows something always. Returns the file.
+ */
+export async function addAllowRule(projectRoot, home, profileName, rule) {
+  parseRule(rule);
+  for (const file of [path.join(projectRoot, '.alp', 'settings.json'), ...(home ? [path.join(home, 'settings.json')] : [])]) {
+    let settings;
+    try { settings = JSON.parse(await readFile(file, 'utf8')); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    const profile = settings?.permissions?.profiles?.[profileName];
+    if (!object(profile)) continue;
+    profile.allow = [...new Set([...(profile.allow ?? []), rule])];
+    validatePermissions(settings.permissions, file);
+    const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`);
+    await moveFile(temporary, file);
+    return file;
+  }
+  throw new AlpError('INVALID_SETTINGS', `No settings file defines profile ${profileName}`);
+}
+
+/** The lower of two modes. */
+export const capMode = (mode, base) => (RANK[mode] ?? 0) <= (RANK[base] ?? 0) ? mode : base;
+
+// --- commands --------------------------------------------------------------------
+
+/** Removes a shell wrapper such as `/bin/zsh -lc '...'` that Codex puts around a command. */
+export function unwrapShell(command) {
+  const match = /^(?:\/\S*\/)?(?:ba|z|da)?sh\s+-l?c\s+(['"])([\s\S]*)\1\s*$/.exec(command.trim());
+  if (!match) return command.trim();
+  return match[1] === "'" ? match[2].replace(/'\\''/g, "'") : match[2].replace(/\\(["\\$`])/g, '$1');
+}
+
+/**
+ * Splits a command line into its simple commands at `&&`, `||`, `;`, `|` and new
+ * lines, outside quotes. Returns null when the line substitutes commands or
+ * processes, or its quotes do not close: no rule can vouch for it.
+ */
+export function simpleCommands(line) {
+  const parts = [];
+  let current = '';
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (char === '\\' && quote === '"') { current += char + (line[++i] ?? ''); continue; }
+      if (char === quote) quote = null;
+      if (quote === '"' && (char === '`' || (char === '$' && line[i + 1] === '('))) return null;
+      current += char;
+      continue;
+    }
+    if (char === '\\') { current += char + (line[++i] ?? ''); continue; }
+    if (char === "'" || char === '"') { quote = char; current += char; continue; }
+    if (char === '`' || (char === '$' && line[i + 1] === '(') || ((char === '<' || char === '>') && line[i + 1] === '(')) return null;
+    const two = line.slice(i, i + 2);
+    // 2>&1 and &>file redirect; they do not end a command.
+    if (two === '>&' || two === '<&' || two === '&>') { current += two; i++; continue; }
+    if (two === '&&' || two === '||') { parts.push(current); current = ''; i++; continue; }
+    if (char === ';' || char === '|' || char === '\n' || char === '&') { parts.push(current); current = ''; continue; }
+    current += char;
+  }
+  if (quote) return null;
+  parts.push(current);
+  return parts.map(part => part.trim()).filter(Boolean);
+}
+
+/** Whether a Bash rule's specifier covers one simple command. */
+function covers(specifier, command) {
+  if (specifier === undefined) return true;
+  const normalized = command.replace(/\s+/g, ' ');
+  // `npm test:*` and `npm test *` both cover npm test and anything after it.
+  if (specifier.endsWith(':*') || specifier.endsWith(' *')) {
+    const prefix = specifier.slice(0, -2).trim().replace(/\s+/g, ' ');
+    return normalized === prefix || normalized.startsWith(`${prefix} `);
+  }
+  if (specifier.endsWith('*')) return normalized.startsWith(specifier.slice(0, -1).replace(/\s+/g, ' '));
+  return normalized === specifier.replace(/\s+/g, ' ');
+}
+
+/** Whether a simple command writes a file through a redirect (not a descriptor or /dev/null). */
+function redirects(command) {
+  const unquoted = command.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, '""');
+  for (const match of unquoted.matchAll(/(?:\d*|&)>>?\s*(&?)(\S*)/g)) {
+    if (match[1] === '&' && /^\d+$/.test(match[2])) continue;
+    if (match[2] === '/dev/null') continue;
+    return true;
+  }
+  return false;
+}
+
+const bashRules = rules => rules.map(rule => parseRule(rule)).filter(rule => rule.tool === 'Bash');
+
+/**
+ * What a profile says about running a command: 'deny' when a deny rule covers any
+ * of its simple commands, 'ask' when an ask rule covers any, 'allow' when allow
+ * rules cover every one of them and none writes through a redirect, otherwise
+ * undefined (the base mode decides).
+ */
+export function commandDecision(profile, command) {
+  const line = unwrapShell(command);
+  const parts = simpleCommands(line);
+  const deny = bashRules(profile.deny);
+  if (deny.some(rule => rule.specifier === undefined)) return 'deny';
+  // A command ALP cannot split may hide anything a deny rule names.
+  if (!parts) return deny.length ? 'deny' : (profile.ask ?? []).length ? 'ask' : undefined;
+  if (parts.some(part => deny.some(rule => covers(rule.specifier, part)))) return 'deny';
+  const ask = bashRules(profile.ask ?? []);
+  if (ask.some(rule => rule.specifier === undefined) || parts.some(part => ask.some(rule => covers(rule.specifier, part)))) return 'ask';
+  const allow = bashRules(profile.allow);
+  if (parts.every(part => !redirects(part) && allow.some(rule => covers(rule.specifier, part)))) return 'allow';
+  return undefined;
+}