@anhlp/alp-core 0.0.0-beta.1

package/src/validation.js

@@ -0,0 +1,302 @@
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { MODELS } from './models.js';
+import { validatePermissions } from './permissions.js';
+import { validateVerify } from './verify.js';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const stringMap = value => object(value) && Object.values(value).every(v => typeof v === 'string');
+function requireValue(condition, code, source, message) {
+  if (!condition) throw new AlpError(code, `${source}: ${message}`);
+}
+
+/** Efforts a profile may name; a model ALP knows takes only its own (src/core/models.js). */
+const EFFORTS = ['none', 'off', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode'];
+/** Top-level keys of a project's .alp/settings.json. */
+export const PROJECT_SETTINGS = ['$schema', 'defaultAgent', 'workflow', 'runtime', 'permissions', 'verify', 'delegation', 'team', 'profile', 'templateDefaults'];
+/** Top-level keys of the user's $ALP_HOME/settings.json. */
+export const USER_SETTINGS = ['$schema', 'language', 'permissions', 'limits', 'recovery', 'web'];
+/**
+ * Top-level keys ALP no longer reads, with what to use instead. They warn rather than
+ * fail, so settings written for an older ALP keep working.
+ */
+export const RETIRED_SETTINGS = { project: {}, user: {} };
+
+/** The edit distance of two short keys, for suggestions. */
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const kept = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1));
+      previous = kept;
+    }
+  }
+  return row[b.length];
+}
+
+/**
+ * Sorts a settings object's top-level keys: unknown ones, with the closest known key
+ * when it is near, and retired ones, with what replaced them.
+ */
+export function settingsKeys(settings, known, retired = {}) {
+  const unknown = [];
+  const old = [];
+  for (const key of Object.keys(object(settings) ? settings : {})) {
+    if (known.includes(key)) continue;
+    if (Object.hasOwn(retired, key)) { old.push({ key, instead: retired[key] }); continue; }
+    const near = known.filter(candidate => !candidate.startsWith('$')).map(candidate => ({ candidate, d: distance(key, candidate) })).sort((a, b) => a.d - b.d)[0];
+    unknown.push({ key, ...(near && near.d <= 2 ? { suggestion: near.candidate } : {}) });
+  }
+  return { unknown, retired: old };
+}
+
+export const unknownMessage = (unknown, known) => `unknown setting '${unknown.key}'${unknown.suggestion ? `; did you mean '${unknown.suggestion}'?` : `; known settings are ${known.filter(key => !key.startsWith('$')).join(', ')}`}`;
+
+/** Warnings for retired keys of a settings object; unknown keys are errors instead. */
+export function settingsWarnings(settings, scope) {
+  return settingsKeys(settings, scope === 'user' ? USER_SETTINGS : PROJECT_SETTINGS, RETIRED_SETTINGS[scope]).retired
+    .map(({ key, instead }) => `setting '${key}' is no longer read; ${instead}`);
+}
+
+export function validateSettings(settings, source) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_SETTINGS', source, message);
+  check(object(settings), 'expected an object');
+  const { unknown } = settingsKeys(settings, PROJECT_SETTINGS, RETIRED_SETTINGS.project);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], PROJECT_SETTINGS) : '');
+  if (settings.defaultAgent !== undefined) check(nonempty(settings.defaultAgent), 'defaultAgent must be a nonempty string');
+  if (settings.workflow !== undefined) {
+    check(object(settings.workflow), 'workflow must be an object');
+    check(Object.keys(settings.workflow).every(key => ['mode', 'maxPeers', 'supervisor'].includes(key)), 'unsupported workflow field');
+    // The team sessions run in (ALPD §42); a session checks that it exists. smart and supervised are Phở and Cafe's names before 0.4.
+    if (settings.workflow.mode !== undefined) check(typeof settings.workflow.mode === 'string' && /^[\w.-]+$/.test(settings.workflow.mode) && settings.workflow.mode !== 'custom', 'workflow.mode must name a team, such as pho or cafe');
+    if (settings.workflow.maxPeers !== undefined) check(Number.isSafeInteger(settings.workflow.maxPeers) && settings.workflow.maxPeers > 0, 'workflow.maxPeers must be a positive integer');
+    if (settings.workflow.supervisor !== undefined) check(typeof settings.workflow.supervisor === 'boolean', 'workflow.supervisor must be true or false');
+  }
+  if (settings.templateDefaults !== undefined) {
+    check(object(settings.templateDefaults), 'templateDefaults must map teams to profile fingerprints');
+    for (const [team, agents] of Object.entries(settings.templateDefaults)) {
+      check(/^[\w.-]+$/.test(team) && object(agents), 'templateDefaults must map teams to profile fingerprints');
+      for (const [agent, hash] of Object.entries(agents)) check(/^[\w.-]+$/.test(agent) && typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash), 'templateDefaults requires profile fingerprints');
+    }
+  }
+  for (const key of ['team', 'profile']) {
+    if (settings[key] === undefined) continue;
+    check(object(settings[key]), `${key} must map team names to agent configurations`);
+    const validateChoice = (config, where) => {
+      check(object(config), `${where} must be an object`);
+      check(Object.keys(config).every(key => ['provider', 'model', 'effort'].includes(key)), `${where}: use provider, model and effort`);
+      if (config.provider !== undefined) check(['codex', 'claude', 'antigravity', 'acp'].includes(config.provider), `${where}.provider must be codex, claude or antigravity`);
+      if (config.model !== undefined) {
+        check(nonempty(config.model) && !/\s/.test(config.model), `${where}.model must be a model ID`);
+        check(config.provider !== undefined || /^(codex|claude|antigravity|acp):.+$/.test(config.model), `${where}: model needs a provider`);
+        if (config.model.includes(':')) check(/^(codex|claude|antigravity|acp):.+$/.test(config.model) && (!config.provider || config.model.startsWith(`${config.provider}:`)), `${where}: model and provider disagree`);
+      }
+      if (config.effort !== undefined) check(EFFORTS.includes(config.effort), `${where}.effort is unsupported`);
+    };
+    for (const [team, agents] of Object.entries(settings[key])) {
+      check(/^[\w.-]+$/.test(team) && object(agents), `${key}.${team} must map agent names to configurations`);
+      for (const [agent, config] of Object.entries(agents)) {
+        const where = `${key}.${team}.${agent}`;
+        check(object(config), `${where} must be an object`);
+        if (config.autocompact !== undefined) validateAutoCompact(config.autocompact, check, `${where}.autocompact`);
+        if (Object.hasOwn(config, 'profiles')) {
+          check(Object.keys(config).every(key => ['profiles', 'autocompact'].includes(key)), `${where}: use profiles and autocompact`);
+          check(Array.isArray(config.profiles) && config.profiles.length > 0, `${where}.profiles must be a nonempty list`);
+          const models = [];
+          for (const [index, entry] of config.profiles.entries()) {
+            if (typeof entry === 'string') {
+              const at = `${where}.profiles[${index}]`;
+              check(/^(codex|claude|antigravity):(\*|[^\s:*]+(:[a-z]+)?)$/.test(entry) || /^acp:[\w.-]+(?:\/[^\s:*]+)?$/.test(entry), `${at} must be "provider:model", "provider:model:effort" (such as "claude:claude-opus-5-5:high"), "acp:provider/model", or "codex:*" / "claude:*" for any model of that provider`);
+              const [provider, model, effort] = entry.split(':');
+              check(model !== '*' || (agent !== 'oracle' && agent !== 'main'), `${at}: ${agent} runs on a named model, not any model`);
+              if (effort !== undefined) {
+                const known = MODELS.find(candidate => candidate.runtime === provider && candidate.id === model);
+                check(EFFORTS.includes(effort), `${at}: effort ${effort} is unsupported`);
+                check(!known?.efforts.length || known.efforts.includes(effort), `${at}: ${provider}:${model} takes effort ${known?.efforts.join(', ')}`);
+              }
+              models.push(`${provider}:${model}`);
+              continue;
+            }
+            validateChoice(entry, `${where}.profiles[${index}]`);
+            check(['claude', 'codex', 'antigravity'].includes(entry.provider) && nonempty(entry.model), `${where}.profiles[${index}]: specify provider and model`);
+            models.push(entry.model.includes(':') ? entry.model : `${entry.provider}:${entry.model}`);
+          }
+          check(new Set(models).size === models.length, `${where}.profiles must not repeat the same model`);
+          check(agent !== 'main' || config.profiles.length === 1, `${where}.profiles: main runs on exactly one model`);
+        } else if (agent === 'oracle') {
+          const entries = Object.entries(config).filter(([key]) => key !== 'autocompact');
+          check(entries.length > 0 && entries.every(([provider]) => ['claude', 'codex'].includes(provider)), `${where} must define profiles or claude/codex lenses`);
+          for (const [provider, lens] of entries) {
+            validateChoice(lens, `${where}.${provider}`);
+            check(lens.provider === provider && nonempty(lens.model), `${where}.${provider}: specify matching provider and model`);
+          }
+        } else {
+          const { autocompact, ...legacy } = config;
+          validateChoice(legacy, where);
+        }
+      }
+    }
+  }
+  validatePermissions(settings.permissions, source);
+  validateVerify(settings.verify, source);
+  const runtime = settings.runtime ?? {};
+  if (settings.runtime !== undefined) check(object(settings.runtime), 'runtime must be an object');
+  for (const key of Object.keys(runtime)) {
+    check(['provider', 'model', 'reasoning'].includes(key), `unsupported runtime field '${key}'`);
+    check(nonempty(runtime[key]), `runtime.${key} must be a nonempty string`);
+  }
+  return { ...runtime };
+}
+
+/** Checks the user's $ALP_HOME/settings.json; returns it. */
+export function validateUserSettings(settings, source) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_SETTINGS', source, message);
+  check(object(settings), 'expected an object');
+  const { unknown } = settingsKeys(settings, USER_SETTINGS, RETIRED_SETTINGS.user);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], USER_SETTINGS) : '');
+  for (const key of ['limits', 'recovery']) {
+    if (settings[key] === undefined) continue;
+    check(object(settings[key]), `${key} must be an object`);
+    const extra = Object.keys(settings[key]).find(field => field !== 'autoResume');
+    check(!extra, `unsupported ${key} field '${extra}'; use autoResume`);
+    if (settings[key].autoResume !== undefined) check(typeof settings[key].autoResume === 'boolean', `${key}.autoResume must be true or false`);
+  }
+  if (settings.web !== undefined) {
+    check(object(settings.web), 'web must be an object');
+    const extra = Object.keys(settings.web).find(field => !['enabled', 'port', 'relay'].includes(field));
+    check(!extra, `unsupported web field '${extra}'; use enabled, port or relay`);
+    // The relay that lets Paseo's app reach alpd from another device (ALPD §64).
+    const relay = settings.web.relay;
+    if (relay !== undefined) {
+      check(object(relay), 'web.relay must be an object');
+      const unsupported = Object.keys(relay).find(field => !['enabled', 'endpoint', 'useTls'].includes(field));
+      check(!unsupported, `unsupported web.relay field '${unsupported}'; use enabled, endpoint or useTls`);
+      if (relay.enabled !== undefined) check(typeof relay.enabled === 'boolean', 'web.relay.enabled must be true or false');
+      if (relay.endpoint !== undefined) check(typeof relay.endpoint === 'string' && /^[a-z0-9.-]+:\d{1,5}$/i.test(relay.endpoint), 'web.relay.endpoint must be host:port, such as relay.paseo.sh:443');
+      if (relay.useTls !== undefined) check(typeof relay.useTls === 'boolean', 'web.relay.useTls must be true or false');
+    }
+    if (settings.web.enabled !== undefined) check(typeof settings.web.enabled === 'boolean', 'web.enabled must be true or false');
+    if (settings.web.port !== undefined) check(Number.isInteger(settings.web.port) && settings.web.port >= 1024 && settings.web.port <= 65535, 'web.port must be a port from 1024 to 65535');
+  }
+  if (settings.language !== undefined) check(nonempty(settings.language) && settings.language.trim().length <= 40, 'language must be a language name of at most 40 characters, such as Vietnamese or English');
+  validatePermissions(settings.permissions, source);
+  return settings;
+}
+
+/** Keys of an agent's agent.json (ALPD §41). */
+export const AGENT_SETTINGS = ['$schema', 'description', 'provider', 'model', 'thinking', 'mode', 'context', 'autocompact', 'skills', 'mcp', 'hooks'];
+/** The context window an agent may set (ALPD §57), in tokens; 'auto' is the model's. */
+export const CONTEXT_TOKENS = { min: 100_000, max: 1_000_000 };
+/** Use the common native compaction-window range; Codex receives the exact token limit. */
+function validateAutoCompact(value, check, where) {
+  check(value === 'auto' || (Number.isSafeInteger(value) && value >= CONTEXT_TOKENS.min && value <= CONTEXT_TOKENS.max),
+    `${where} must be "auto" or a number of tokens from ${CONTEXT_TOKENS.min} to ${CONTEXT_TOKENS.max}`);
+}
+const AGENT_MODES = ['read-only', 'workspace-write', 'full-access'];
+const entryName = value => typeof value === 'string' && /^[\w.-]+$/.test(value) && value !== '.' && value !== '..';
+
+export const HOOK_SETTINGS = ['$schema', 'description', 'event', 'command', 'blocking', 'timeoutSec', 'match'];
+/** The events ALP runs hooks at (ALPD §41); only those before an action can refuse it. */
+export const HOOK_EVENTS = ['session.start', 'turn.end', 'assignment.start', 'assignment.end', 'handoff', 'task.close', 'merge'];
+export const BLOCKING_HOOK_EVENTS = ['handoff', 'task.close', 'merge'];
+
+/** Checks a hook definition, hooks/<name>.json: a shell command ALP runs at one of its events. */
+export function validateHook(config, source) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_HOOK', source, message);
+  check(object(config), 'expected an object');
+  const { unknown } = settingsKeys(config, HOOK_SETTINGS);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], HOOK_SETTINGS) : '');
+  if (config.description !== undefined) check(typeof config.description === 'string', 'description must be a string');
+  check(HOOK_EVENTS.includes(config.event), `event must be one of ${HOOK_EVENTS.join(', ')}`);
+  check(nonempty(config.command), 'command must be a nonempty string');
+  if (config.blocking !== undefined) {
+    check(typeof config.blocking === 'boolean', 'blocking must be true or false');
+    check(!config.blocking || BLOCKING_HOOK_EVENTS.includes(config.event), `only ${BLOCKING_HOOK_EVENTS.join(', ')} hooks can block`);
+  }
+  if (config.timeoutSec !== undefined) check(Number.isInteger(config.timeoutSec) && config.timeoutSec >= 1 && config.timeoutSec <= 3600, 'timeoutSec must be a whole number of seconds from 1 to 3600');
+  if (config.match !== undefined) {
+    check(object(config.match) && Object.keys(config.match).every(key => ['agent', 'label'].includes(key)), 'match may hold only agent and label');
+    for (const key of ['agent', 'label']) if (config.match[key] !== undefined) check(nonempty(config.match[key]), `match.${key} must be a nonempty string`);
+  }
+  return config;
+}
+
+/** Checks an agent's agent.json: what it runs on, its default mode, and the skills, MCP servers and hooks it names. */
+export function validateAgentConfig(config, source) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_AGENT_CONFIG', source, message);
+  check(object(config), 'expected an object');
+  const { unknown } = settingsKeys(config, AGENT_SETTINGS);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], AGENT_SETTINGS) : '');
+  if (config.description !== undefined) check(typeof config.description === 'string', 'description must be a string');
+  for (const key of ['provider', 'model', 'thinking']) if (config[key] !== undefined) check(nonempty(config[key]), `${key} must be a nonempty string`);
+  if (config.mode !== undefined) check(AGENT_MODES.includes(config.mode), `mode must be one of ${AGENT_MODES.join(', ')}`);
+  if (config.context !== undefined) {
+    check(config.context === 'auto' || (Number.isSafeInteger(config.context) && config.context >= CONTEXT_TOKENS.min && config.context <= CONTEXT_TOKENS.max),
+      `context must be "auto" or a number of tokens from ${CONTEXT_TOKENS.min} to ${CONTEXT_TOKENS.max}`);
+  }
+  if (config.autocompact !== undefined) validateAutoCompact(config.autocompact, check, 'autocompact');
+  for (const key of ['skills', 'mcp', 'hooks']) {
+    if (config[key] === undefined) continue;
+    check(Array.isArray(config[key]) && config[key].every(entryName), `${key} must list names of letters, digits, '.', '_' or '-'`);
+    check(new Set(config[key]).size === config[key].length, `${key} lists a name twice`);
+  }
+  return config;
+}
+
+export function normalizeMcp(raw, directory, source) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_MCP', source, message);
+  check(object(raw), 'expected an object');
+  check(Object.keys(raw).every(k => k === 'mcpServers'), 'only mcpServers is supported');
+  const servers = raw.mcpServers === undefined ? {} : raw.mcpServers;
+  check(object(servers), 'mcpServers must be an object');
+  const normalized = [];
+  for (const [name, server] of Object.entries(servers)) {
+    check(nonempty(name) && object(server), `invalid server '${name}'`);
+    check(Object.keys(server).every(k => ['command', 'args', 'cwd', 'env', 'url', 'headers'].includes(k)), `${name}: unsupported server field`);
+    check(nonempty(server.command) !== nonempty(server.url), `${name}: specify exactly one of command or url`);
+    const result = { ...server };
+    if (server.command !== undefined) check(nonempty(server.command), `${name}.command must be nonempty`);
+    if (server.url !== undefined) {
+      check(nonempty(server.url), `${name}.url must be nonempty`);
+      let url; try { url = new URL(server.url); } catch { /* validation below */ }
+      check(url && ['https:', 'http:'].includes(url.protocol), `${name}.url must be an HTTP(S) URL`);
+      check(server.args === undefined && server.cwd === undefined && server.env === undefined, `${name}: args/cwd/env require command`);
+    }
+    if (server.args !== undefined) check(Array.isArray(server.args) && server.args.every(v => typeof v === 'string'), `${name}.args must be strings`);
+    for (const key of ['env', 'headers']) if (server[key] !== undefined) check(stringMap(server[key]), `${name}.${key} must map strings to strings`);
+    if (server.command !== undefined) check(server.headers === undefined, `${name}: headers require url`);
+    if (server.cwd !== undefined) {
+      check(nonempty(server.cwd), `${name}.cwd must be nonempty`);
+      result.cwd = path.resolve(directory, server.cwd);
+    }
+    // Bare executables remain PATH lookups; explicit relative command paths are agent-relative.
+    if (server.command && /[\\/]/.test(server.command)) result.command = path.resolve(directory, server.command);
+    normalized.push([name, result]);
+  }
+  return { mcpServers: Object.fromEntries(normalized) };
+}
+
+export function validateResolvedAgent(agent) {
+  const check = (ok, message) => requireValue(ok, 'INVALID_RESOLVED_AGENT', 'ResolvedAgent', message);
+  check(object(agent), 'expected an object');
+  check(nonempty(agent.name), 'name is required');
+  check(typeof agent.projectRoot === 'string' && path.isAbsolute(agent.projectRoot), 'projectRoot must be absolute');
+  check(object(agent.instructions) && typeof agent.instructions.project === 'string' && typeof agent.instructions.agent === 'string', 'instructions must contain project and agent strings');
+  for (const key of ['skills', 'hooks']) {
+    check(Array.isArray(agent[key]), `${key} must be an array`);
+    for (const resource of agent[key]) check(object(resource) && nonempty(resource.name) && typeof resource.path === 'string' && path.isAbsolute(resource.path), `${key} must contain named absolute paths`);
+  }
+  check(object(agent.runtime), 'runtime must be an object');
+  validateSettings({ runtime: agent.runtime }, 'ResolvedAgent.runtime');
+  normalizeMcp(agent.mcp, agent.projectRoot, 'ResolvedAgent.mcp');
+  check(object(agent.mcp.mcpServers), 'MCP must contain a normalized mcpServers map');
+  for (const server of Object.values(agent.mcp.mcpServers)) {
+    if (server.cwd !== undefined) check(path.isAbsolute(server.cwd), 'MCP cwd must already be absolute');
+    if (server.command && /[\\/]/.test(server.command)) check(path.isAbsolute(server.command), 'MCP command paths must already be absolute');
+  }
+  return agent;
+}

package/src/verify.d.ts

@@ -0,0 +1,15 @@
+export const VERIFY_STEPS: readonly ['setup', 'typecheck', 'test'];
+export const VERIFY_TIMEOUT_SEC: number;
+export const VERIFY_GRACE_MS: number;
+export const VERIFY_INFRA_EXIT: number;
+
+export type VerifyConfig = { setup?: string; typecheck?: string; test?: string; timeoutSec: number; idleSec?: number };
+
+export type VerifyCommand = { step: 'setup' | 'typecheck' | 'test'; command: string; exitCode: number; ms: number; output: string; timedOut?: boolean; idle?: boolean };
+
+export type Verification = { passed: boolean; cwd: string; commands: VerifyCommand[]; skipped?: string };
+
+export function validateVerify(verify: unknown, source: string): VerifyConfig | undefined;
+export function verifyConfig(projectRoot: string): Promise<VerifyConfig | undefined>;
+export function runVerify(cwd: string, config: VerifyConfig, options?: { env?: NodeJS.ProcessEnv }): Promise<Verification>;
+export function describeVerification(verified: { passed: boolean; commands: Array<{ step: string; exitCode: number; timedOut?: boolean; idle?: boolean }>; skipped?: string }): string;

package/src/verify.js

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { signalShell, spawnShell } from './shell.js';
+
+/**
+ * The project's verification gate (plans/reference/ALPD.md §28): commands from
+ * `verify` in .alp/settings.json that alpd runs before it applies an assignment's
+ * change, and after a writer in the shared checkout. They run in order and stop
+ * at the first failure.
+ */
+
+export const VERIFY_STEPS = ['setup', 'typecheck', 'test'];
+export const VERIFY_TIMEOUT_SEC = 600;
+/** How long a stopped command gets between SIGTERM and SIGKILL. */
+export const VERIFY_GRACE_MS = 5000;
+/** The exit code (EX_TEMPFAIL) by which a step says it could not run, rather than that the change is wrong. */
+export const VERIFY_INFRA_EXIT = 75;
+const COMMAND_CHARS = 2000;
+const OUTPUT_CHARS = 4000;
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (source, message) => { throw new AlpError('INVALID_SETTINGS', `${source}: ${message}`); };
+
+/** Checks a `verify` setting; returns it normalized, or undefined when absent. */
+export function validateVerify(verify, source) {
+  if (verify === undefined) return undefined;
+  if (!object(verify)) fail(source, 'verify must be an object');
+  const extra = Object.keys(verify).filter(key => ![...VERIFY_STEPS, 'timeoutSec', 'idleSec'].includes(key));
+  if (extra.length) fail(source, `unsupported verify field '${extra[0]}'; use ${VERIFY_STEPS.join(', ')}, timeoutSec and idleSec`);
+  for (const step of VERIFY_STEPS) {
+    if (verify[step] !== undefined && (typeof verify[step] !== 'string' || !verify[step].trim() || verify[step].length > COMMAND_CHARS)) fail(source, `verify.${step} must be a command of at most ${COMMAND_CHARS} characters`);
+  }
+  if (!VERIFY_STEPS.some(step => verify[step] !== undefined)) fail(source, `verify needs at least one of ${VERIFY_STEPS.join(', ')}`);
+  if (verify.timeoutSec !== undefined && (!Number.isSafeInteger(verify.timeoutSec) || verify.timeoutSec < 1 || verify.timeoutSec > 7200)) fail(source, 'verify.timeoutSec must be 1 to 7200 seconds');
+  if (verify.idleSec !== undefined && (!Number.isSafeInteger(verify.idleSec) || verify.idleSec < 1 || verify.idleSec > 7200)) fail(source, 'verify.idleSec must be 1 to 7200 seconds');
+  return {
+    ...Object.fromEntries(VERIFY_STEPS.filter(step => verify[step] !== undefined).map(step => [step, verify[step].trim()])),
+    timeoutSec: verify.timeoutSec ?? VERIFY_TIMEOUT_SEC,
+    ...(verify.idleSec !== undefined ? { idleSec: verify.idleSec } : {}),
+  };
+}
+
+/** The project's verify setting, or undefined when it has none. */
+export async function verifyConfig(projectRoot) {
+  const file = path.join(projectRoot, '.alp', 'settings.json');
+  let text;
+  try { text = await readFile(file, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  let settings;
+  try { settings = JSON.parse(text); } catch (error) { fail(file, `invalid JSON: ${error.message}`); }
+  return object(settings) ? validateVerify(settings.verify, file) : undefined;
+}
+
+/**
+ * Runs one command through the shell, keeping the end of its output. When it runs
+ * past `timeoutMs`, or prints nothing for `idleMs`, its process group gets SIGTERM,
+ * then SIGKILL after VERIFY_GRACE_MS, so its own cleanup can run.
+ */
+function runCommand(command, cwd, { timeoutMs, idleMs }, env) {
+  return new Promise(resolve => {
+    const started = Date.now();
+    const child = spawnShell(command, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    let stopped;
+    let idle;
+    const signal = name => signalShell(child, name);
+    const stop = reason => {
+      if (stopped) return;
+      stopped = reason;
+      signal('SIGTERM');
+      setTimeout(() => signal('SIGKILL'), VERIFY_GRACE_MS).unref();
+    };
+    const quiet = () => {
+      if (!idleMs) return;
+      clearTimeout(idle);
+      idle = setTimeout(() => stop('idle'), idleMs);
+    };
+    const keep = chunk => { output = (output + chunk).slice(-OUTPUT_CHARS * 2); quiet(); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    quiet();
+    const timer = setTimeout(() => stop('timeout'), timeoutMs);
+    let done = false;
+    const finish = (exitCode, error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      clearTimeout(idle);
+      const tail = output.length > OUTPUT_CHARS ? `…${output.slice(-OUTPUT_CHARS)}` : output;
+      resolve({
+        exitCode, ms: Date.now() - started, output: error ? `${tail}${error}` : tail,
+        ...(stopped === 'timeout' ? { timedOut: true } : stopped === 'idle' ? { idle: true } : {}),
+        ...(error ? { spawnError: true } : {}),
+      });
+    };
+    child.once('error', error => finish(127, error.message));
+    child.once('close', (code, signal) => finish(stopped ? 124 : code ?? (signal ? 128 : 1)));
+  });
+}
+
+/**
+ * Runs the configured steps in `cwd`, in order, stopping at the first failure.
+ * A step that exits VERIFY_INFRA_EXIT, or whose shell does not start, ends the run as skipped.
+ * @returns {Promise<{ passed: boolean, cwd: string, skipped?: string, commands: Array<{ step: string, command: string, exitCode: number, ms: number, output: string, timedOut?: boolean, idle?: boolean }> }>}
+ */
+export async function runVerify(cwd, config, { env = process.env } = {}) {
+  const commands = [];
+  for (const step of VERIFY_STEPS) {
+    if (!config[step]) continue;
+    const { spawnError, ...result } = await runCommand(config[step], cwd, { timeoutMs: config.timeoutSec * 1000, idleMs: config.idleSec ? config.idleSec * 1000 : undefined }, { ...env, ALP_VERIFY: '1' });
+    commands.push({ step, command: config[step], ...result });
+    // A step that could not run says nothing about the change: the check is skipped, not failed.
+    if (spawnError || result.exitCode === VERIFY_INFRA_EXIT) {
+      return { passed: false, cwd, commands, skipped: `infra: ${step} could not run (${spawnError ? 'the shell did not start' : `exit ${VERIFY_INFRA_EXIT}`})` };
+    }
+    if (result.exitCode !== 0) return { passed: false, cwd, commands };
+  }
+  return { passed: true, cwd, commands };
+}
+
+/** One line for a verification: passed, or the step that failed. */
+export function describeVerification(verified) {
+  if (verified.skipped) return `verification skipped: ${verified.skipped}`;
+  const failed = verified.commands.find(command => command.exitCode !== 0);
+  return verified.passed ? `verified (${verified.commands.map(command => command.step).join(', ')})`
+    : `verification failed: ${failed.step} ${failed.timedOut ? 'timed out' : failed.idle ? 'printed nothing for too long' : `exited ${failed.exitCode}`}`;
+}

package/src/workflow.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { jsonObject } from './resolver.js';
+import { applyProfile } from './profiles.js';
+import { validateSettings } from './validation.js';
+import { resolveTeam, teamOf } from './teams.js';
+
+export { teamOf as profileOf } from './teams.js';
+
+/**
+ * The team a session runs in (ALPD §42): the one the caller selects, the one a resumed
+ * session ran in, or settings' workflow.mode. Without any, the session is `custom`: its
+ * graph is settings' delegation and no supervisor watches it.
+ * @returns {Promise<{ mode: string, maxPeers: number, supervisor: boolean, team?: Awaited<ReturnType<typeof resolveTeam>> }>}
+ */
+export async function resolveWorkflow(root, selected, restored, { library, templates } = {}) {
+  const settings = await jsonObject(path.join(root, '.alp/settings.json'), 'INVALID_SETTINGS');
+  validateSettings(settings, '.alp/settings.json');
+  const chosen = selected === undefined ? undefined : teamOf(selected);
+  if (chosen === 'custom') throw new Error('Choose a team, such as pho (Phở) or cafe (Cafe)');
+  const mode = chosen ?? teamOf(restored?.mode ?? settings.workflow?.mode ?? 'custom');
+  if (restored && mode !== teamOf(restored.mode)) throw new Error('Cannot change team in an existing session');
+  const team = mode === 'custom' ? undefined : applyProfile(await resolveTeam(root, mode, { library, templates }), (settings.team ?? settings.profile)?.[mode]);
+  const maxPeers = restored?.maxPeers ?? settings.workflow?.maxPeers ?? team?.maxPeers ?? 2;
+  if (!Number.isSafeInteger(maxPeers) || maxPeers < 1) throw new Error('workflow.maxPeers must be a positive integer');
+  // A custom delegation graph has no main to supervise; settings can turn a team's supervisor off.
+  const supervisor = !!team?.supervisor && (restored?.supervisor ?? settings.workflow?.supervisor ?? true);
+  return { mode, maxPeers, supervisor, ...(team ? { team } : {}) };
+}

package/templates/ALP.md

@@ -0,0 +1,52 @@
+# ALP project instructions
+
+## Working relationship
+
+The user communicates with main. The team is fixed for each session:
+
+- Phở (default): main owns delivery and technical execution; it implements
+  directly or delegates bounded work to peer. There is no separate lead.
+- Cafe: main owns the outcome and supervises lead; lead implements or
+  delegates to peer. Main routes implementation changes through lead.
+
+In both, main runs by default on Opus 5.5 with high effort and full access,
+and starts a supervisor that reviews the process after each of main's turns.
+The supervisor asks main about mistakes; main answers and records lessons it
+follows later.
+
+Oracle provides read-only advice through the configured model lenses; reviewer independently
+reviews one diff. Both return once only to the requesting coordinator. They do
+not spawn agents. Default maximum concurrent peers is two; raise the configured
+limit only at the user's request. Other model and effort choices belong to the
+technical coordinator. A role grants no additional filesystem permissions,
+credentials, or runtime tools.
+
+## Shared work contract
+
+- Read project instructions and the selected agent's AGENT.md. Load skills only
+  when needed; do not assume that skills or tools from another runtime exist.
+- Each assignment states its objective, root, owned/excluded paths, constraints
+  and their sources, verification, resources, owner, and expected handoff.
+- Keep a single writer per shared checkout. Transfer ownership before main or lead
+  intervenes in a peer's files. Parallel writers need isolated workspaces and
+  explicit shared-interface agreements.
+- Return artifacts and real verification evidence, with remaining risks. A worker's
+  completion message is a candidate, not an independent acceptance verdict.
+- Review should be independent of authorship: the coordinator reviews peer work;
+  in Cafe, main reviews lead work. Use reviewer for logic changes and risky
+  changes, including main-authored changes. Disclose unavailable independent review
+  rather than claiming it occurred.
+- Changes to scope or priorities flow through the technical coordinator's current plan
+  and the affected peer's revised brief. Direct questions can receive direct answers;
+  an exceptional intervention must be reconciled with the same shared state.
+- Tasks live in `.alp/tasks` and are shared with the user. Only the user and main
+  create or change them; other agents read them and report work they find to their
+  requester.
+- Use only actual runtime delegation/messaging capabilities. Without them, explain
+  the limitation, perform authorized work directly where possible, and never claim
+  that a lead or peer session ran or reviewed anything.
+
+## Project-specific constraints
+
+Add the project's outcome, boundaries, verification commands, and authorization
+requirements here. User instructions take precedence over this starter workflow.

package/templates/agents/lead/AGENT.md

@@ -0,0 +1,90 @@
+# Lead — technical execution owner
+
+Receive the task from main and own technical delivery within its assigned root and
+scope. Main represents the user's goal and coordinates the broader outcome. Route
+questions, progress, and the final deliverable to main; contact the user directly
+only for an explicit exception.
+
+## Workflow and model choices
+
+You own technical execution in Cafe. Small tasks may be completed directly;
+peer delegation is optional. Main remains the user-facing supervisor. Phở uses
+main as technical coordinator and does not create this role.
+
+Choose model and effort separately for each peer assignment by the task's difficulty,
+uncertainty, risk, and autonomy needs. When peer's model profiles offer a choice (several
+models, or any model of a provider), pick a model they offer and its effort for every
+assignment and say why in modelReason; otherwise use the runtime catalog. The default
+limit is two concurrent peers. Increase only at the user's request via configuration.
+Serialize writing assignments in the shared checkout; concurrent peers must be
+read-only. Never bypass these limits using native spawning or shell-launched agents.
+
+Call oracle for significant uncertainty and reviewer for logic changes or risky
+changes; trivial typo/format edits may skip review. Brief reviewer with the
+acceptance criteria; its verdict judges each one with evidence, and a `fail` or
+`blocked` result goes back to work before you hand off. Oracle runs on the configured oracle models listed in your runtime instructions; for two independent
+opinions, consult both in parallel. Never substitute another model when one is
+unavailable; report it. Advisors return once to you; evaluate their evidence
+and report unresolved findings to main.
+Use available plan/usage/reset snapshots to avoid exhausted limits; missing or stale
+data must remain explicitly uncertain and does not imply unlimited usage.
+
+## Background first
+
+- Delegate in the background, as alp_delegate does by default, with `etaMinutes`,
+  and go on with work that does not depend on the result. Pass `wait: true` only
+  when your next step cannot go on without it.
+- When only results are left, alp_wait for them. Mail from main ends the wait
+  early: act on it, pass on what changes a peer's work with alp_send, then wait
+  again.
+- Run long shell commands (builds, test suites, servers) in the background when
+  your tools allow it.
+
+## Execution
+
+- Inspect the current implementation and user changes before planning work.
+- Decompose the outcome, resolve dependencies, assign ownership, and keep the plan
+  current. Make technical decisions within the brief and project constraints.
+- Delegate bounded outcomes to peer using real runtime capabilities. A peer may
+  implement, research, design, or review according to its brief; these are tasks,
+  not additional built-in roles.
+- Give each peer the task identity, root, objective, constraint sources, owned and
+  excluded paths, write/read authority, base revision when available, verification,
+  resources, and expected handoff. Avoid prescribing an unverified solution.
+- Keep one writer per shared checkout. For concurrent writers allocate isolated
+  workspaces and nonconflicting resources. Main intervention requires an explicit
+  ownership transfer and an updated brief before work resumes.
+- You may implement directly. Identify your authored changes in the handoff so
+  main can review them; do not self-accept your own implementation.
+- Check progress and blockers through supported runtime mechanisms. Missing
+  messaging or delegation is a capability limitation, not proof of worker activity.
+
+## Review and escalation
+
+Review peer candidates using the actual diff/artifact and command outputs. Where
+Git is available, verify base and candidate revisions and owned paths. Issue an
+explicit ACCEPT or REJECT with concrete findings; test success alone is insufficient.
+Return your aggregate outcome, changed paths, verification, peer verdicts, risks,
+and ownership status to main. List work you or your peers found outside the scope
+under discovered: only main and the user create tasks, and main records it. When
+main gave you a task, your peers' claims carry its id, and your handoff moves it
+to review for main to accept. In a non-Git project, identify the actual changed
+files and evidence without inventing commit identifiers.
+
+Peer objections are evidence to investigate. Resolve technical matters in scope;
+send scope/priority conflicts or missing authority to main. When main or the user
+changes direction, update the plan, then deliver revised briefs to affected peers
+and confirm their receipt before relying on the new direction.
+
+If delegation is unavailable, report that fact to main and perform authorized work
+directly where possible. Do not claim that a peer executed or reviewed the task.
+
+## Skills
+
+Read the applicable SKILL.md from the runtime skill index before using its method;
+do not preload all bodies. Use xia for unfamiliar implementation,
+sequence-execution-plan for dependencies, and prompt-leverage before assigning peer.
+Use bug-loop for diagnosis/corrections and smart-commits when commits are part of
+your authorized deliverable. Identify a relevant installed method in the peer brief.
+Intake with the user belongs to main: return material missing decisions to main,
+including them in the handoff when there is no live upstream messaging channel.