alp-code 0.9.0

package/dist/src/cli/alp.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAlpArgs = parseAlpArgs;
+exports.main = main;
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const modes_1 = require("../agents/modes");
+const registry_1 = require("../agents/registry");
+const local_process_backend_1 = require("../backend/local-process-backend");
+const execution_service_1 = require("../execution/execution-service");
+const execution_store_1 = require("../execution/execution-store");
+const markdown_file_store_1 = require("../memory/adapters/markdown-file-store");
+const memory_service_1 = require("../memory/memory-service");
+const policy_engine_1 = require("../policy/policy-engine");
+const claude_adapter_1 = require("../runtime/claude-adapter");
+const codex_adapter_1 = require("../runtime/codex-adapter");
+const mode_selector_1 = require("./mode-selector");
+const workflow_runner_1 = require("../workflow/workflow-runner");
+const context_1 = require("./commands/context");
+const delegate_1 = require("./commands/delegate");
+const identity_sync_1 = require("./commands/identity-sync");
+const init_1 = require("./commands/init");
+const principal_1 = require("./commands/principal");
+const run_main_1 = require("./commands/run-main");
+const mode_1 = require("./commands/mode");
+const state_paths_1 = require("../state-paths");
+const update_check_1 = require("./update-check");
+/** Lời nhắn cho mọi chỗ còn gọi runtime — cờ, subcommand, hay tên CLI trần. */
+const RUNTIME_IS_GONE = "runtime không còn là lựa chọn: nấc quyết định model, model quyết định CLI — dùng `alp --mode <nấc>` hoặc `alp mode set <nấc>`";
+/**
+ * `alp [--mode <nấc>]` — một cờ duy nhất. Gõ sai thì dừng ngay chứ không rơi về mặc định, vì
+ * một phiên chạy nấc khác nấc người dùng tưởng là im lặng tốn tiền hoặc im lặng yếu đi.
+ */
+function parseRunMainFlags(argv) {
+    let mode;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === "--runtime" || value.startsWith("--runtime="))
+            throw new Error(RUNTIME_IS_GONE);
+        if (value !== "--mode" && !value.startsWith("--mode=")) {
+            throw new Error(`unknown option \`${value}\`; usage: alp [--mode ${modes_1.MODE_IDS.join("|")}]`);
+        }
+        let raw;
+        if (value === "--mode") {
+            raw = argv[index + 1];
+            index += 1;
+        }
+        else {
+            raw = value.slice("--mode=".length);
+        }
+        if (mode !== undefined)
+            throw new Error("multiple mode selections are not allowed");
+        if (raw === undefined || raw === "")
+            throw new Error("alp --mode accepts exactly one mode");
+        mode = (0, modes_1.parseMode)(raw);
+    }
+    return { command: "run-main", ...(mode ? { mode } : {}) };
+}
+function parseAlpArgs(argv) {
+    if (argv.length === 0)
+        return { command: "run-main" };
+    if (argv[0].startsWith("--mode") || argv[0].startsWith("--runtime"))
+        return parseRunMainFlags(argv);
+    if (argv[0] === "--version" || argv[0] === "-v") {
+        if (argv.length !== 1)
+            throw new Error("alp --version does not accept arguments");
+        return { command: "version" };
+    }
+    if (["claude", "codex", "run-role"].includes(argv[0]) || argv[0] === "--role") {
+        throw new Error("direct raw runtime launch is unsupported; use `alp` or `alp --mode <nấc>`");
+    }
+    if (argv[0] === "runtime")
+        throw new Error(RUNTIME_IS_GONE);
+    if (argv[0] === "mode") {
+        if (argv[1] === "show" && argv.length === 2)
+            return { command: "mode", action: "show" };
+        if (argv[1] === "set" && argv.length === 3)
+            return { command: "mode", action: "set", mode: (0, modes_1.parseMode)(argv[2]) };
+        throw new Error(`usage: alp mode show | alp mode set <${modes_1.MODE_IDS.join("|")}>`);
+    }
+    if (argv[0] === "init") {
+        let project;
+        for (let index = 1; index < argv.length; index += 1) {
+            const value = argv[index];
+            if (value.startsWith("-"))
+                throw new Error(`unknown init option \`${value}\``);
+            if (project !== undefined)
+                throw new Error("alp init accepts one project path");
+            project = value;
+        }
+        return { command: "init", ...(project ? { project } : {}) };
+    }
+    if (argv[0] === "deinit") {
+        if (argv.length > 2 || argv[1]?.startsWith("-"))
+            throw new Error("usage: alp deinit [path]");
+        return { command: "deinit", ...(argv[1] ? { project: argv[1] } : {}) };
+    }
+    if (argv[0] === "identity") {
+        if (argv[1] === "sync" && argv.length === 2)
+            return { command: "identity", action: "sync" };
+        throw new Error("usage: alp identity sync");
+    }
+    if (argv[0] === "principal") {
+        if ((argv[1] === "show" || argv[1] === "set") && argv.length === 2) {
+            return { command: "principal", action: argv[1] };
+        }
+        throw new Error("usage: alp principal show | alp principal set");
+    }
+    if (argv[0] === "delegate")
+        return { command: "delegate", args: Object.freeze(argv.slice(1)) };
+    if (argv[0] === "delegation")
+        return { command: "delegation", args: Object.freeze(argv.slice(1)) };
+    if (argv[0] === "context")
+        return { command: "context", args: Object.freeze(argv.slice(1)) };
+    if (argv[0] === "doctor") {
+        if (argv.slice(1).some((value) => value !== "--quiet"))
+            throw new Error("usage: alp doctor [--quiet]");
+        return { command: "maintenance", action: "doctor", args: Object.freeze(argv.slice(1)) };
+    }
+    if (argv[0] === "update") {
+        if (argv.length !== 1)
+            throw new Error("alp update does not accept arguments");
+        return { command: "maintenance", action: "update", args: Object.freeze([]) };
+    }
+    if (argv[0] === "uninstall") {
+        if (argv.slice(1).some((value) => value !== "--purge-memory" && value !== "--force")) {
+            throw new Error("usage: alp uninstall [--purge-memory] [--force]");
+        }
+        return { command: "maintenance", action: "uninstall", args: Object.freeze(argv.slice(1)) };
+    }
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h")
+        return { command: "help" };
+    throw new Error(`unknown command \`${argv[0]}\``);
+}
+function findRepoRoot(start) {
+    let directory = (0, node_path_1.resolve)(start);
+    for (;;) {
+        try {
+            (0, node_fs_1.accessSync)((0, node_path_1.join)(directory, "package.json"));
+            return directory;
+        }
+        catch { /* continue */ }
+        const parent = (0, node_path_1.dirname)(directory);
+        if (parent === directory)
+            throw new Error("cannot locate alp-code repository root");
+        directory = parent;
+    }
+}
+function readVersion(repoRoot) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, "package.json"), "utf8"));
+        return typeof parsed?.version === "string" ? parsed.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function defaultDependencies(cwd, stdout, stderr) {
+    const repoRoot = process.env.ALP_REPO_ROOT || findRepoRoot(__dirname);
+    const version = readVersion(repoRoot);
+    const policy = new policy_engine_1.PolicyEngine({ registry: registry_1.agentRegistry });
+    const memory = new memory_service_1.MemoryService({
+        store: new markdown_file_store_1.MarkdownFileStore({ root: (0, state_paths_1.memoryRoot)() }),
+        policy,
+        audit: { record() { } },
+    });
+    const executionService = new execution_service_1.ExecutionService({
+        registry: registry_1.agentRegistry,
+        policy,
+        memory,
+        workflowRunner: new workflow_runner_1.WorkflowRunner(),
+        store: new execution_store_1.FileExecutionStore({ root: (0, state_paths_1.executionsDirectory)() }),
+    });
+    const adapters = new Map([
+        ["claude", new claude_adapter_1.ClaudeRuntimeAdapter({ hooksDirectory: (0, node_path_1.join)(repoRoot, "hooks") })],
+        // Previously left to default to `ALP_REPO_ROOT` (set by `scripts/alp.cjs`) the way
+        // Claude's constructor already falls back too. That implicit path was fine carrying two
+        // hooks; wiring two more onto it (PreCompact/PostCompact) turns a coincidence into a
+        // real dependency, so it is passed explicitly here like Claude's.
+        ["codex", new codex_adapter_1.CodexRuntimeAdapter({ hooksDirectory: (0, node_path_1.join)(repoRoot, "hooks") })],
+    ]);
+    const backend = new local_process_backend_1.LocalProcessBackend();
+    const selector = new mode_selector_1.ModeSelector({ output: stdout });
+    const projectRegistry = new init_1.ProjectRegistryStore();
+    return {
+        cwd,
+        stdout,
+        stderr,
+        version,
+        async checkForUpdate() {
+            if (process.env.ALP_SKIP_UPDATE_CHECK === "1")
+                return null;
+            try {
+                return await (0, update_check_1.checkForUpdate)({ repoRoot, store: new update_check_1.FileUpdateCheckStore(), currentVersion: version });
+            }
+            catch {
+                return null;
+            }
+        },
+        async runMain(input) {
+            const result = await (0, run_main_1.runMainSession)(input, {
+                registry: registry_1.agentRegistry,
+                selector,
+                executionService,
+                adapters,
+                backend,
+                executionId: () => `exec_${(0, node_crypto_1.randomUUID)().replaceAll("-", "").slice(0, 20)}`,
+                interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                workspaceModeFor: async (project) => (await projectRegistry.isRegistered(project))
+                    ? "workspace-write"
+                    : "read-only",
+            });
+            return result.status === "completed" ? 0 : result.status === "cancelled" ? 130 : 1;
+        },
+        async modeCommand(input) {
+            await (0, mode_1.runModeCommand)(input, { write: (text) => stdout.write(text) });
+            return 0;
+        },
+        async initProject(input) {
+            const registered = await (0, init_1.initializeProject)({ ...input, repoRoot }, { store: projectRegistry });
+            // Asked before the identity sync below, because the answers are rendered into every
+            // `.alp/agents/<role>.md` this install writes.
+            await (0, principal_1.ensurePrincipalProfile)({ interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY) }, { write: (text) => stdout.write(text) });
+            // Identity documents are what the SessionStart hook reads; a project registered
+            // without them would boot with an empty identity and a warning.
+            await (0, identity_sync_1.syncIdentityDocuments)({ directory: (0, state_paths_1.agentsDirectory)() }, { registry: registry_1.agentRegistry });
+            stdout.write(`READY    ${registered.path}\n`);
+        },
+        async deinitProject(input) {
+            await (0, init_1.deinitializeProject)({ ...input, repoRoot }, { store: projectRegistry });
+            stdout.write(`REMOVED  ${(0, node_path_1.resolve)(input.project)}\n`);
+        },
+        async syncIdentity() {
+            const written = await (0, identity_sync_1.syncIdentityDocuments)({ directory: (0, state_paths_1.agentsDirectory)() }, { registry: registry_1.agentRegistry });
+            for (const file of written)
+                stdout.write(`IDENTITY ${file}\n`);
+        },
+        async principalCommand(input) {
+            return (0, principal_1.runPrincipalCommand)(input, {
+                write: (text) => stdout.write(text),
+                // A changed name must reach the generated identity documents, or the next native
+                // session would boot with the previous one.
+                syncIdentity: async () => { await (0, identity_sync_1.syncIdentityDocuments)({ directory: (0, state_paths_1.agentsDirectory)() }, { registry: registry_1.agentRegistry }); },
+            });
+        },
+        async delegateCommand(args) {
+            const lifecycle = args[0] === "__lifecycle";
+            const actual = lifecycle ? args.slice(1) : args;
+            const composition = await (0, delegate_1.createDefaultDelegationComposition)(repoRoot, process.env);
+            const value = lifecycle
+                ? await (0, delegate_1.runDelegationLifecycleCommand)(actual, composition.service)
+                : await (0, delegate_1.runDelegateCommand)(actual, { cwd, env: process.env, service: composition.service });
+            stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+            return typeof value === "object" && value !== null && "status" in value && value.status === "failed" ? 1 : 0;
+        },
+        async contextCommand(args) {
+            return (0, context_1.runContextCommand)(args, {
+                executionsRoot: (0, state_paths_1.executionsDirectory)(),
+                env: process.env,
+                write: (text) => stdout.write(text),
+            });
+        },
+        async maintenanceCommand(input) {
+            if (input.action === "doctor") {
+                const checked = (0, node_child_process_1.spawnSync)(process.execPath, [(0, node_path_1.join)(repoRoot, "scripts", "doctor.cjs"), ...input.args], {
+                    cwd,
+                    env: process.env,
+                    stdio: "inherit",
+                });
+                if (checked.error)
+                    throw checked.error;
+                return checked.status ?? 2;
+            }
+            if (input.action === "update") {
+                const updater = (0, node_module_1.createRequire)(__filename)((0, node_path_1.join)(repoRoot, "scripts", "lib", "update.cjs"));
+                const result = await updater.updateInstallation(repoRoot, {
+                    env: process.env,
+                    stdio: "inherit",
+                    log(level, message) { stdout.write(`${level.padEnd(9)}${message}\n`); },
+                });
+                if (!result.ok)
+                    stderr.write(`ERROR     ${result.message ?? "update failed"}\n`);
+                return result.ok ? 0 : 1;
+            }
+            const uninstall = (0, node_module_1.createRequire)(__filename)((0, node_path_1.join)(repoRoot, "scripts", "lib", "uninstall.cjs"));
+            const result = uninstall.uninstall(repoRoot, {
+                cwd,
+                purgeMemory: input.args.includes("--purge-memory"),
+                force: input.args.includes("--force"),
+            });
+            for (const entry of result.log)
+                stdout.write(`${entry.level.padEnd(8)} ${entry.text}\n`);
+            if (result.memoryBackup)
+                stdout.write(`RESTORE  ${result.memoryBackup}\n`);
+            return 0;
+        },
+    };
+}
+function helpText() {
+    return [
+        "alp — code-native agent launcher",
+        "",
+        `  alp [--mode ${modes_1.MODE_IDS.join("|")}]`,
+        "  alp mode show|set <mode>",
+        "  alp init [path]",
+        "  alp deinit [path]",
+        "  alp identity sync",
+        "  alp principal show|set",
+        "  alp delegate <role> [options] -- <task>",
+        "  alp context status|validate [execution-id]",
+        "  alp context pin <decision|constraint|open-item|next-action> -- <text>",
+        "  alp context unpin <pin-id>",
+        "  alp doctor",
+        "  alp update [--verbose]",
+        "  alp uninstall [--purge-memory] [--force]",
+        "  alp --version",
+        "",
+        "Mode quyết định model của từng vai, và model quyết định CLI nào chạy vai đó.",
+        "Thứ tự: --mode → ALP_MODE → `alp mode set` → hỏi trên TTY → `medium`.",
+        "",
+        ...modes_1.MODE_IDS.map((mode) => `  ${mode.padEnd(7)} ${modes_1.MODE_PROFILES[mode].summary}`),
+        "",
+        "Direct `claude`, `codex`, and identity-aware raw-runtime shortcuts are unsupported.",
+    ].join("\n") + "\n";
+}
+async function main(argv = process.argv.slice(2), injected) {
+    const cwd = injected?.cwd ?? process.cwd();
+    const stdout = injected?.stdout ?? process.stdout;
+    const stderr = injected?.stderr ?? process.stderr;
+    const dependencies = injected ?? defaultDependencies(cwd, stdout, stderr);
+    const command = parseAlpArgs(argv);
+    const notice = await dependencies.checkForUpdate().catch(() => null);
+    if (notice)
+        stdout.write(notice);
+    if (command.command === "version") {
+        stdout.write(`alp ${dependencies.version}\n`);
+        return 0;
+    }
+    if (command.command === "run-main") {
+        // Cờ thắng biến môi trường; `ALP_MODE` tồn tại để một phiên delegated kế thừa nấc của cha.
+        const inheritedMode = process.env.ALP_MODE ? (0, modes_1.parseMode)(process.env.ALP_MODE) : undefined;
+        const mode = command.mode ?? inheritedMode;
+        return dependencies.runMain({ cwd, ...(mode ? { mode } : {}) });
+    }
+    if (command.command === "mode")
+        return dependencies.modeCommand(command);
+    if (command.command === "init") {
+        await dependencies.initProject({ project: (0, node_path_1.resolve)(cwd, command.project ?? ".") });
+        return 0;
+    }
+    if (command.command === "deinit") {
+        await dependencies.deinitProject({ project: (0, node_path_1.resolve)(cwd, command.project ?? ".") });
+        return 0;
+    }
+    if (command.command === "identity") {
+        await dependencies.syncIdentity();
+        return 0;
+    }
+    if (command.command === "principal")
+        return dependencies.principalCommand({ action: command.action });
+    if (command.command === "delegate")
+        return dependencies.delegateCommand(command.args);
+    if (command.command === "delegation")
+        return dependencies.delegateCommand(Object.freeze(["__lifecycle", ...command.args]));
+    if (command.command === "context")
+        return dependencies.contextCommand(command.args);
+    if (command.command === "maintenance")
+        return dependencies.maintenanceCommand({ action: command.action, args: command.args });
+    stdout.write(helpText());
+    return 0;
+}
+if (require.main === module) {
+    main().then((code) => { process.exitCode = code; }, (error) => {
+        process.stderr.write(`ERROR     ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+    });
+}

package/dist/src/cli/commands/context.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContextCommand = runContextCommand;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const checkpoint_1 = require("../../context/checkpoint");
+const compact_journal_1 = require("../../context/compact-journal");
+const continuity_1 = require("../../context/continuity");
+const adapter_files_1 = require("../../runtime/adapter-files");
+const claude_adapter_1 = require("../../runtime/claude-adapter");
+const codex_adapter_1 = require("../../runtime/codex-adapter");
+const EXECUTION_ID_PATTERN = /^exec_[a-zA-Z0-9_-]+$/;
+const PIN_KINDS = ["decision", "constraint", "open-item", "next-action"];
+const PIN_FIELD = {
+    decision: "decisions",
+    constraint: "constraints",
+    "open-item": "openItems",
+    "next-action": "nextActions",
+};
+const USAGE = "usage: alp context status|validate [execution-id] | alp context pin <decision|constraint|open-item|next-action> -- <text> | alp context unpin <pin-id>";
+function isPinKind(value) {
+    return PIN_KINDS.includes(value ?? "");
+}
+/** Positional first, `ALP_DELEGATION_EXECUTION_ID` second — no ambiguous "latest" guess. */
+function resolveExecutionId(positional, env) {
+    const id = positional || env.ALP_DELEGATION_EXECUTION_ID;
+    if (!id)
+        throw new Error(USAGE);
+    if (!EXECUTION_ID_PATTERN.test(id))
+        throw new Error(`invalid execution ID \`${id}\``);
+    return id;
+}
+function contextPaths(executionsRoot, executionId) {
+    const directory = (0, node_path_1.join)(executionsRoot, executionId);
+    const contextDirectory = (0, node_path_1.join)(directory, "context");
+    return {
+        policyFile: (0, node_path_1.join)(directory, "policy.json"),
+        checkpointFile: (0, node_path_1.join)(contextDirectory, "checkpoint.json"),
+        continuityFile: (0, node_path_1.join)(contextDirectory, "continuity.md"),
+        compactEventsFile: (0, node_path_1.join)(contextDirectory, "compact-events.jsonl"),
+    };
+}
+async function readPolicyHash(executionId, policyFile) {
+    let raw;
+    try {
+        raw = await (0, promises_1.readFile)(policyFile, "utf8");
+    }
+    catch (error) {
+        throw new Error(`execution \`${executionId}\` not found: ${error.message}`);
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.policyHash !== "string" || parsed.policyHash.length === 0) {
+        throw new Error(`policy file carries no policyHash: ${policyFile}`);
+    }
+    return parsed.policyHash;
+}
+/**
+ * Reuses the same pinned capability each adapter already carries rather than keeping a
+ * second copy of it here — a version bump that changes `sessionStartAfterCompact` only ever
+ * has to be made in one place.
+ */
+function compactCapabilityFor(runtime) {
+    return runtime === "claude" ? new claude_adapter_1.ClaudeRuntimeAdapter().compact : new codex_adapter_1.CodexRuntimeAdapter().compact;
+}
+async function commandStatus(argv, dependencies) {
+    const executionId = resolveExecutionId(argv[0], dependencies.env);
+    const paths = contextPaths(dependencies.executionsRoot, executionId);
+    const policyHash = await readPolicyHash(executionId, paths.policyFile);
+    await (0, compact_journal_1.rotateCompactJournalIfNeeded)(paths.compactEventsFile);
+    const replay = await (0, compact_journal_1.replayCompactJournal)(paths.compactEventsFile);
+    const state = (0, compact_journal_1.reduceCompactJournal)(replay.events);
+    const checkpointResult = await (0, checkpoint_1.readCheckpoint)(paths.checkpointFile, { executionId, policyHash });
+    const write = dependencies.write;
+    write(`EXECUTION  ${executionId}\n`);
+    if (checkpointResult.ok) {
+        const checkpoint = checkpointResult.value;
+        write(`OBJECTIVE  ${checkpoint.objective ?? "(none)"}\n`);
+        write(`PINS       decisions=${checkpoint.decisions.length} constraints=${checkpoint.constraints.length} `
+            + `open-items=${checkpoint.openItems.length} next-actions=${checkpoint.nextActions.length}\n`);
+    }
+    else {
+        // Fail closed per invariant 6: this is the same reason a runtime would refuse to inject
+        // it, surfaced here instead of silently.
+        write(`WARNING    checkpoint not usable: ${checkpointResult.reason}\n`);
+    }
+    write(`GENERATION ${state.generation}\n`);
+    write(`PENDING    ${state.pending ? `${state.pending.runtime} ${state.pending.trigger} (started ${state.pending.observedAt})` : "(none)"}\n`);
+    write(`COMPLETED  ${state.lastCompleted ? `${state.lastCompleted.runtime} ${state.lastCompleted.trigger} (at ${state.lastCompleted.observedAt})` : "(none)"}\n`);
+    const observedRuntime = state.pending?.runtime ?? state.lastCompleted?.runtime ?? null;
+    const restore = observedRuntime === null
+        ? "unknown — no compaction observed yet"
+        : compactCapabilityFor(observedRuntime).sessionStartAfterCompact
+            ? "reinjected at the next SessionStart"
+            : "next-session (persist-only; this runtime does not reinject)";
+    write(`RESTORE    ${restore}\n`);
+    if (replay.droppedLines > 0)
+        write(`WARNING    journal has ${replay.droppedLines} line(s) that failed to parse and were skipped\n`);
+    return 0;
+}
+async function commandValidate(argv, dependencies) {
+    const executionId = resolveExecutionId(argv[0], dependencies.env);
+    const paths = contextPaths(dependencies.executionsRoot, executionId);
+    const policyHash = await readPolicyHash(executionId, paths.policyFile);
+    await (0, compact_journal_1.rotateCompactJournalIfNeeded)(paths.compactEventsFile);
+    const replay = await (0, compact_journal_1.replayCompactJournal)(paths.compactEventsFile);
+    const state = (0, compact_journal_1.reduceCompactJournal)(replay.events);
+    // Reducing twice over the same events is the cheapest possible regression guard for
+    // invariant 14 (idempotent lifecycle) — the function is pure, so a mismatch here would mean
+    // a real bug, not noise.
+    const stable = JSON.stringify(state) === JSON.stringify((0, compact_journal_1.reduceCompactJournal)(replay.events));
+    const checkpointResult = await (0, checkpoint_1.readCheckpoint)(paths.checkpointFile, { executionId, policyHash });
+    const write = dependencies.write;
+    write(`EXECUTION  ${executionId}\n`);
+    write(`CHECKPOINT ${checkpointResult.ok ? "valid" : `INVALID — ${checkpointResult.reason}`}\n`);
+    write(`JOURNAL    ${replay.events.length} event(s), ${replay.droppedLines} dropped line(s)\n`);
+    write(`REPLAY     ${stable ? "stable" : "UNSTABLE"}\n`);
+    write(`GENERATION ${state.generation}\n`);
+    return checkpointResult.ok && stable ? 0 : 1;
+}
+/** A pin is one sentence: control characters (newlines included) collapse to a single space. */
+function sanitizePinText(raw) {
+    return raw.replace(/[\x00-\x1F\x7F]/g, " ").replace(/\s+/g, " ").trim();
+}
+async function loadCheckpointForMutation(executionId, paths, action) {
+    const policyHash = await readPolicyHash(executionId, paths.policyFile);
+    const result = await (0, checkpoint_1.readCheckpoint)(paths.checkpointFile, { executionId, policyHash });
+    if (!result.ok)
+        throw new Error(`cannot ${action}: ${result.reason}`);
+    return result.value;
+}
+async function persistCheckpoint(paths, checkpoint) {
+    const written = await (0, checkpoint_1.writeCheckpoint)(paths.checkpointFile, checkpoint);
+    await (0, adapter_files_1.atomicRuntimeFile)(paths.continuityFile, (0, continuity_1.renderContinuity)(written));
+    return written;
+}
+async function commandPin(argv, dependencies) {
+    const kind = argv[0];
+    if (!isPinKind(kind))
+        throw new Error(USAGE);
+    const separator = argv.indexOf("--");
+    if (separator === -1 || separator === argv.length - 1)
+        throw new Error(USAGE);
+    const text = sanitizePinText(argv.slice(separator + 1).join(" "));
+    if (text.length === 0)
+        throw new Error("pin text is empty after sanitizing control characters");
+    if (Buffer.byteLength(text, "utf8") > checkpoint_1.PIN_MAX_BYTES)
+        throw new Error(`pin text exceeds ${checkpoint_1.PIN_MAX_BYTES} bytes`);
+    const executionId = resolveExecutionId(undefined, dependencies.env);
+    const paths = contextPaths(dependencies.executionsRoot, executionId);
+    const checkpoint = await loadCheckpointForMutation(executionId, paths, "pin");
+    const now = (dependencies.now ?? (() => new Date().toISOString()))();
+    const pin = {
+        id: (0, node_crypto_1.randomUUID)(),
+        text,
+        source: dependencies.env.ALP_DELEGATED_ROLE ? "agent" : "principal",
+        createdAt: now,
+    };
+    const field = PIN_FIELD[kind];
+    await persistCheckpoint(paths, { ...checkpoint, [field]: [...checkpoint[field], pin], updatedAt: now });
+    dependencies.write(`PINNED     ${pin.id}\n`);
+    return 0;
+}
+async function commandUnpin(argv, dependencies) {
+    const pinId = argv[0];
+    if (!pinId)
+        throw new Error(USAGE);
+    const executionId = resolveExecutionId(undefined, dependencies.env);
+    const paths = contextPaths(dependencies.executionsRoot, executionId);
+    const checkpoint = await loadCheckpointForMutation(executionId, paths, "unpin");
+    let found = false;
+    const next = {
+        decisions: checkpoint.decisions,
+        constraints: checkpoint.constraints,
+        openItems: checkpoint.openItems,
+        nextActions: checkpoint.nextActions,
+    };
+    for (const field of Object.keys(next)) {
+        const filtered = checkpoint[field].filter((pin) => pin.id !== pinId);
+        if (filtered.length !== checkpoint[field].length)
+            found = true;
+        next[field] = filtered;
+    }
+    // Checked before any write: an unknown ID must leave the checkpoint byte-for-byte as it was.
+    if (!found)
+        throw new Error(`no pin with ID \`${pinId}\``);
+    const now = (dependencies.now ?? (() => new Date().toISOString()))();
+    await persistCheckpoint(paths, { ...checkpoint, ...next, updatedAt: now });
+    dependencies.write(`UNPINNED   ${pinId}\n`);
+    return 0;
+}
+async function runContextCommand(argv, dependencies) {
+    const [sub, ...rest] = argv;
+    if (sub === "status")
+        return commandStatus(rest, dependencies);
+    if (sub === "validate")
+        return commandValidate(rest, dependencies);
+    if (sub === "pin")
+        return commandPin(rest, dependencies);
+    if (sub === "unpin")
+        return commandUnpin(rest, dependencies);
+    throw new Error(USAGE);
+}