@paleo/alcode 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @paleo/alcode
+
+Run a coding agent through [AlignFirst](https://github.com/paleo/alignfirst) protocols from the terminal. `alcode` wraps a coding-agent CLI for non-interactive use: it invokes a protocol (`spec`, `plan`, `aad`, …), streams the run to a per-call session file under `.plans/`, and returns the result.
+
+Run `alcode --guide` for the full delegation guide. When an OpenClaw agent is the caller, run `alcode --openclaw-guide` instead: the same manual, with the OpenClaw-specific run instructions (`exec` with `background: true` + `timeout: 0`, and the completion-wake procedure).
+
+## Execution model
+
+`alcode` runs the coding agent as a direct **foreground** child of its own process: it streams a live transcript to stdout and to a per-run session file (with a YAML frontmatter status lifecycle `running` → `succeeded`/`failed`), and blocks until the agent exits. It never backgrounds or detaches itself.
+
+Coding runs can be very long: the caller always runs `alcode` as a background task and owns the backgrounding. Under OpenClaw the agent invokes `alcode` through the `exec` tool with `background: true` and `timeout: 0`. OpenClaw wakes the agent on exit (via `tools.exec.notifyOnExit`), which then reads the session file for the result. This keeps the run's lifecycle owned by one supervisor (the caller) instead of a detached process phoning back in. The session file is the durable result handoff: frontmatter `sessionId` + status, and the `---- Result ----` block.
+
+If `alcode` is terminated, its signal handlers seal the session file (`status: failed`, `exitReason: terminated`) so it never stays frozen at `running`, then send `SIGTERM` to the coding-agent child, giving it a short grace to tear down its own subprocesses before a `SIGKILL` backstop guarantees no orphan is left behind. Only a `SIGKILL` of `alcode` itself (uncatchable) can leave a stale `running` status.
+
+## Usage
+
+```bash
+alcode --new --protocol spec --ticket AB-123 --message "Feature description"
+alcode --resume <sessionId> --protocol plan
+alcode --new --message "Execute the plan: .plans/AB-123/A2-plan.md"
+```
+
+See `alcode --help` for all flags and environment variables.

package/bin/alcode.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+process.exit(await main());

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+import { type RunConfig, type RunOutput } from "./run-claude.js";
+export interface MainOptions {
+    argv?: string[];
+    stdout?: RunOutput;
+    stderr?: RunOutput;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function main(options?: MainOptions): Promise<number>;
+export declare function buildRunConfig(parsed: AlcodeArgs, cwd: string, sessionFilePath: string, env: NodeJS.ProcessEnv): RunConfig;
+export interface AlcodeArgs {
+    isNew: boolean;
+    resume?: string;
+    ticket?: string;
+    protocol?: string;
+    message?: string;
+    model?: string;
+    guide: boolean;
+    openclawGuide: boolean;
+    help: boolean;
+}
+export declare function parseAlcodeArgs(argv: string[]): AlcodeArgs;
+export declare function validateArgs(args: AlcodeArgs): string | undefined;

package/dist/cli.js

@@ -0,0 +1,193 @@
+import { relative } from "node:path";
+import { parseArgs } from "node:util";
+import { renderGuide } from "./guide.js";
+import { assertPlansGate, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
+import { buildPrompt, PROTOCOLS } from "./prompt.js";
+import { runClaude } from "./run-claude.js";
+export async function main(options) {
+    const argv = options?.argv ?? process.argv;
+    const stdout = options?.stdout ?? process.stdout;
+    const stderr = options?.stderr ?? process.stderr;
+    const cwd = options?.cwd ?? process.cwd();
+    const env = options?.env ?? process.env;
+    let parsed;
+    try {
+        parsed = parseAlcodeArgs(argv);
+    }
+    catch (err) {
+        stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    if (parsed.help) {
+        stdout.write(renderHelp());
+        return 0;
+    }
+    if (parsed.guide || parsed.openclawGuide) {
+        stdout.write(`${renderGuide(parsed.openclawGuide ? "openclaw" : "generic")}\n`);
+        return 0;
+    }
+    const validationError = validateArgs(parsed);
+    if (validationError) {
+        stderr.write(`${validationError}\n`);
+        return 1;
+    }
+    return runSession(parsed, { cwd, env, stdout, stderr });
+}
+// alcode always runs `claude` in the foreground and blocks until it exits. When OpenClaw drives
+// alcode, it wraps this call in its own `exec` tool (which backgrounds after `yieldMs` and wakes
+// the agent on exit) — alcode owns no backgrounding or callback of its own. The per-run session
+// file under `.plans/` is the durable result handoff: on completion the frontmatter carries the
+// session id and status, and the `---- Result ----` block carries the outcome for a waking agent
+// (or a human).
+async function runSession(parsed, ctx) {
+    const { cwd, env, stdout, stderr } = ctx;
+    const gateError = assertPlansGate(cwd);
+    if (gateError) {
+        stderr.write(`${gateError}\n`);
+        return 1;
+    }
+    const now = new Date();
+    const sessionFilePath = resolveSessionFilePath(cwd, parsed.ticket, now);
+    writeInitialSessionFile(sessionFilePath, buildFrontmatter(parsed, now));
+    stdout.write(`Session file: ${relative(cwd, sessionFilePath)}\n\n`);
+    const result = await runClaude(buildRunConfig(parsed, cwd, sessionFilePath, env), stdout);
+    if (parsed.isNew && result.sessionId) {
+        stdout.write(`\nSession ID: ${result.sessionId}\n`);
+    }
+    return result.status === "succeeded" ? 0 : 1;
+}
+function buildFrontmatter(parsed, now) {
+    return {
+        status: "running",
+        protocol: parsed.protocol ?? null,
+        ticket: parsed.ticket ?? null,
+        model: parsed.model ?? null,
+        sessionId: null,
+        command: formatCommand(parsed),
+        startedAt: now.toISOString(),
+        endedAt: null,
+        exitReason: null,
+    };
+}
+export function buildRunConfig(parsed, cwd, sessionFilePath, env) {
+    return {
+        prompt: buildPrompt(parsed),
+        sessionFilePath,
+        cwd,
+        isNew: parsed.isNew,
+        resume: parsed.resume,
+        model: parsed.model,
+        skipPermissions: env.ALIGNFIRST_CODE_SKIP_PERMISSIONS === "1",
+        unset: (env.ALIGNFIRST_CODE_UNSET ?? "").split(","),
+        env,
+    };
+}
+function formatCommand(parsed) {
+    const parts = ["alcode"];
+    if (parsed.isNew)
+        parts.push("--new");
+    if (parsed.resume)
+        parts.push("--resume", parsed.resume);
+    if (parsed.protocol)
+        parts.push("--protocol", parsed.protocol);
+    if (parsed.ticket)
+        parts.push("--ticket", parsed.ticket);
+    if (parsed.model)
+        parts.push("--model", parsed.model);
+    if (parsed.message)
+        parts.push("--message", JSON.stringify(parsed.message));
+    return parts.join(" ");
+}
+export function parseAlcodeArgs(argv) {
+    const { values } = parseArgs({
+        args: argv.slice(2),
+        options: {
+            new: { type: "boolean", default: false },
+            resume: { type: "string" },
+            ticket: { type: "string" },
+            protocol: { type: "string" },
+            message: { type: "string" },
+            model: { type: "string" },
+            guide: { type: "boolean", default: false },
+            "openclaw-guide": { type: "boolean", default: false },
+            help: { type: "boolean", default: false },
+        },
+        strict: true,
+    });
+    return {
+        isNew: values.new === true,
+        resume: values.resume,
+        ticket: values.ticket,
+        protocol: values.protocol,
+        message: values.message,
+        model: values.model,
+        guide: values.guide === true,
+        openclawGuide: values["openclaw-guide"] === true,
+        help: values.help === true,
+    };
+}
+export function validateArgs(args) {
+    const isResume = args.resume !== undefined;
+    if (args.isNew && isResume)
+        return "Error: --new and --resume are mutually exclusive.";
+    if (!args.isNew && !isResume)
+        return "Error: at least one of --new or --resume is required.";
+    if (args.protocol !== undefined && !PROTOCOLS.includes(args.protocol)) {
+        return `Error: --protocol must be one of: ${PROTOCOLS.join(", ")}.`;
+    }
+    if (!args.protocol && !args.message) {
+        return "Error: --message is required when --protocol is not specified.";
+    }
+    if (args.isNew && args.protocol && !args.ticket) {
+        return "Error: --ticket is required with --new and --protocol.";
+    }
+    if (["spec", "aad"].includes(args.protocol ?? "") && !args.message) {
+        return `Error: --protocol ${args.protocol} requires --message.`;
+    }
+    if (args.ticket !== undefined && !args.isNew) {
+        return "Error: --ticket is only valid with --new.";
+    }
+    if (args.ticket !== undefined && !isPathSafeTicket(args.ticket)) {
+        return ("Error: --ticket must be a single path segment " +
+            "(letters, digits, '.', '-', '_'); no path separators or '..'.");
+    }
+    return;
+}
+// The ticket becomes a `.plans/<ticket>/coding-sessions/…` path segment. Ticket formats vary by
+// consumer repo (numeric here, but e.g. `AB-123` elsewhere), so allow a permissive charset while
+// blocking path separators and `..` traversal that could escape `.plans/`.
+function isPathSafeTicket(ticket) {
+    return /^[A-Za-z0-9._-]+$/.test(ticket) && ticket !== "." && !ticket.includes("..");
+}
+function renderHelp() {
+    return `alcode — run a coding agent through AlignFirst protocols.
+
+Usage:
+  alcode --new --protocol <protocol> --ticket <id> [--message "..."]
+  alcode --new --message "..."
+  alcode --resume <sessionId> [--protocol <protocol>] [--message "..."]
+  alcode --guide
+  alcode --openclaw-guide
+  alcode --help
+
+Modes:
+  --new                 Start a new session.
+  --resume <sessionId>  Continue an existing session.
+
+Options:
+  --protocol <p>    One of: ${PROTOCOLS.join(", ")}.
+  --ticket <id>     Ticket ID. Required with --new + --protocol.
+  --message "..."   Message to send. Required for spec, aad, and when no --protocol.
+  --model <model>   Model override.
+
+Env:
+  ALIGNFIRST_CODE_SKIP_PERMISSIONS 1 to run the coding agent with permission prompts disabled.
+  ALIGNFIRST_CODE_UNSET            Comma-list of env vars to strip from the coding agent child.
+
+alcode runs a coding agent in the foreground and blocks until it finishes, streaming the
+transcript to stdout and to a session file under .plans/. Coding runs can be very long: always
+run alcode as a background task. Your platform does the backgrounding; never detach alcode.
+
+Run \`alcode --guide\` for the full delegation guide (\`alcode --openclaw-guide\` under OpenClaw).
+`;
+}

package/dist/guide.d.ts

@@ -0,0 +1,2 @@
+export type GuideVariant = "generic" | "openclaw";
+export declare function renderGuide(variant: GuideVariant): string;

package/dist/guide.js

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+// templates/guide.md is the shared skeleton; the per-variant fragments fill its tags:
+//   {{TITLE-SUFFIX}} — appended to the H1 to label the variant
+//   {{RUN}}          — how to background the run on the caller's platform
+//   {{WAKE}}         — how the completion wake arrives, introducing the shared steps
+export function renderGuide(variant) {
+    return readTemplate("guide.md")
+        .replaceAll("{{TITLE-SUFFIX}}", variant === "openclaw" ? " (OpenClaw)" : "")
+        .replaceAll("{{RUN}}", readTemplate(`guide-run-${variant}.md`).trimEnd())
+        .replaceAll("{{WAKE}}", readTemplate(`guide-wake-${variant}.md`).trimEnd())
+        .trimEnd();
+}
+function readTemplate(name) {
+    return readFileSync(new URL(`../templates/${name}`, import.meta.url), "utf-8");
+}

package/dist/prompt.d.ts

@@ -0,0 +1,9 @@
+export declare const PROTOCOLS: readonly ["spec", "plan", "aad", "description", "read", "review", "merge"];
+export type Protocol = (typeof PROTOCOLS)[number];
+export declare const PROTOCOL_LABELS: Record<string, string>;
+export interface PromptInput {
+    protocol?: string;
+    ticket?: string;
+    message?: string;
+}
+export declare function buildPrompt(input: PromptInput): string;

package/dist/prompt.js

@@ -0,0 +1,27 @@
+export const PROTOCOLS = ["spec", "plan", "aad", "description", "read", "review", "merge"];
+export const PROTOCOL_LABELS = {
+    spec: "spec",
+    aad: "AAD",
+    plan: "plan",
+    description: "description",
+    review: "review",
+    merge: "merge",
+};
+export function buildPrompt(input) {
+    const { protocol, ticket, message } = input;
+    if (!protocol)
+        return message ?? "";
+    if (protocol === "read")
+        return buildReadPrompt(ticket, message);
+    return buildProtocolPrompt(PROTOCOL_LABELS[protocol], ticket, message);
+}
+function buildReadPrompt(ticket, message) {
+    const ticketPart = ticket ? ` for ticket ${ticket}` : "";
+    const messagePart = message ? `\n\n${message}` : "";
+    return `Use the *alignfirst* skill to determine the TASK_DIR${ticketPart}. Then read every \`*spec.md\` and \`*summary.md\` file in the TASK_DIR.${messagePart}`;
+}
+function buildProtocolPrompt(label, ticket, message) {
+    const ticketPart = ticket ? ` Ticket ID = ${ticket}.` : "";
+    const messagePart = message ? `\n\n${message}` : "";
+    return `Run the _${label}_ protocol from the *alignfirst* skill.${ticketPart}${messagePart}`;
+}

package/dist/run-claude.d.ts

@@ -0,0 +1,32 @@
+import { type CompletionUpdate } from "./session-file.js";
+export interface RunConfig {
+    prompt: string;
+    sessionFilePath: string;
+    cwd: string;
+    isNew: boolean;
+    resume?: string;
+    model?: string;
+    skipPermissions: boolean;
+    unset: string[];
+    env: NodeJS.ProcessEnv;
+}
+export interface RunOutput {
+    write(text: string): void;
+}
+export interface RunResult {
+    status: "succeeded" | "failed";
+    sessionId: string | null;
+    result: string;
+}
+export declare function runClaude(config: RunConfig, out: RunOutput): Promise<RunResult>;
+export declare function buildTerminationUpdate(signal: NodeJS.Signals, state: StreamState, now: Date): CompletionUpdate;
+export declare function buildClaudeArgs(config: RunConfig): string[];
+export declare function buildClaudeEnv(baseEnv: NodeJS.ProcessEnv, unset: string[]): NodeJS.ProcessEnv;
+export interface StreamState {
+    sessionId?: string;
+    result?: string;
+    isError: boolean;
+}
+export declare function createStreamState(): StreamState;
+export declare function parseEventLine(line: string): unknown;
+export declare function renderEvent(event: unknown, state: StreamState): string | undefined;

package/dist/run-claude.js

@@ -0,0 +1,268 @@
+import { spawn } from "node:child_process";
+import { appendTranscript, applyCompletion } from "./session-file.js";
+// Grace period between the SIGTERM that lets `claude` tear down its own children and the SIGKILL
+// backstop that guarantees alcode never leaves a dangling child.
+const TERMINATION_GRACE_MS = 2000;
+// Runs `claude` as a direct foreground child of this process: parses its NDJSON stream, mirrors a
+// human-readable transcript to both the session file and `out` as it arrives, and on exit rewrites
+// the session file's terminal frontmatter and returns the outcome. OpenClaw backgrounds *alcode*
+// via its own `exec` tool and wakes on alcode's exit — alcode itself never detaches.
+export async function runClaude(config, out) {
+    const state = createStreamState();
+    const outcome = await spawnClaude(config, state, out);
+    const failed = state.isError || outcome.exitCode !== 0 || state.result === undefined;
+    const result = state.result ?? failureMessage(outcome);
+    applyCompletion(config.sessionFilePath, {
+        status: failed ? "failed" : "succeeded",
+        endedAt: new Date().toISOString(),
+        exitReason: failed ? "error" : "completed",
+        sessionId: state.sessionId ?? null,
+        result,
+    });
+    return { status: failed ? "failed" : "succeeded", sessionId: state.sessionId ?? null, result };
+}
+function spawnClaude(config, state, out) {
+    const child = spawn("claude", buildClaudeArgs(config), {
+        cwd: config.cwd,
+        env: buildClaudeEnv(config.env, config.unset),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const detachChildGuards = guardChildLifecycle(child, config.sessionFilePath, state);
+    let buffer = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf-8");
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk;
+        buffer = drainLines(buffer, (line) => emitEvent(config.sessionFilePath, line, state, out));
+    });
+    child.stderr.setEncoding("utf-8");
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    return new Promise((resolve) => {
+        child.on("close", (code) => {
+            if (buffer.trim())
+                emitEvent(config.sessionFilePath, buffer, state, out);
+            detachChildGuards();
+            resolve({ exitCode: code, stderr });
+        });
+        child.on("error", (err) => {
+            detachChildGuards();
+            resolve({ exitCode: 1, stderr: err.message });
+        });
+    });
+}
+// A direct `kill <alcode>` (not a process-group kill) would otherwise orphan the foreground
+// `claude`. On a catchable signal, seal the session file (`status: failed`, `exitReason:
+// terminated`) so it never stays frozen at `running`, then SIGTERM the child and give it a short
+// grace to tear down *its own* children (tool subprocesses, dev servers) before a SIGKILL backstop
+// guarantees nothing dangles. The synchronous `exit` handler can't await, so it does a last-resort
+// SIGKILL. A SIGKILL of alcode itself remains the one uncatchable case. Returns a teardown that
+// removes the guards once the child is gone (so alcode can exit normally afterward).
+function guardChildLifecycle(child, sessionFilePath, state) {
+    const isAlive = () => child.exitCode === null && child.signalCode === null;
+    const signalChild = (signal) => {
+        if (!isAlive())
+            return;
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The child is already gone; nothing to clean up.
+        }
+    };
+    const forceKill = () => signalChild("SIGKILL");
+    const onSignal = async (signal) => {
+        try {
+            applyCompletion(sessionFilePath, buildTerminationUpdate(signal, state, new Date()));
+        }
+        catch {
+            // Sealing the session file is best-effort; the file may be gone or malformed.
+        }
+        signalChild("SIGTERM");
+        await waitForChildExit(child, TERMINATION_GRACE_MS);
+        forceKill();
+        process.exit(signal === "SIGINT" ? 130 : 143);
+    };
+    const onSigint = () => onSignal("SIGINT");
+    const onSigterm = () => onSignal("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    process.on("exit", forceKill);
+    return () => {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        process.off("exit", forceKill);
+    };
+}
+// Resolves when the child exits or the grace period elapses, whichever comes first — so a SIGTERM
+// that `claude` honors lets alcode exit promptly, while a hung child still hits the SIGKILL backstop.
+function waitForChildExit(child, graceMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const onExit = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            child.off("exit", onExit);
+            resolve();
+        }, graceMs);
+        child.once("exit", onExit);
+    });
+}
+export function buildTerminationUpdate(signal, state, now) {
+    return {
+        status: "failed",
+        endedAt: now.toISOString(),
+        exitReason: "terminated",
+        sessionId: state.sessionId ?? null,
+        result: `Terminated by ${signal} before completion.`,
+    };
+}
+export function buildClaudeArgs(config) {
+    const args = [config.prompt, "-p", "--output-format", "stream-json", "--verbose"];
+    if (config.skipPermissions) {
+        args.push("--dangerously-skip-permissions");
+    }
+    else {
+        args.push("--permission-mode", "auto");
+    }
+    if (config.resume)
+        args.push("--resume", config.resume);
+    if (config.model)
+        args.push("--model", config.model);
+    return args;
+}
+// Strip every ALIGNFIRST_CODE_* var plus any name in the caller's ALIGNFIRST_CODE_UNSET list, so
+// wrapper env never leaks into the claude child.
+export function buildClaudeEnv(baseEnv, unset) {
+    const env = { ...baseEnv };
+    for (const name of unset) {
+        const trimmed = name.trim();
+        if (trimmed)
+            delete env[trimmed];
+    }
+    for (const key of Object.keys(env)) {
+        if (key.startsWith("ALIGNFIRST_CODE_"))
+            delete env[key];
+    }
+    return env;
+}
+function drainLines(buffer, onLine) {
+    const lines = buffer.split("\n");
+    const rest = lines.pop() ?? "";
+    for (const line of lines) {
+        if (line.trim())
+            onLine(line);
+    }
+    return rest;
+}
+function emitEvent(sessionFilePath, line, state, out) {
+    const rendered = renderEvent(parseEventLine(line), state);
+    if (rendered === undefined)
+        return;
+    appendTranscript(sessionFilePath, `${rendered}\n`);
+    out.write(`${rendered}\n`);
+}
+export function createStreamState() {
+    return { isError: false };
+}
+export function parseEventLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { type: "unparsed", raw: line };
+    }
+}
+// Mutates `state` (session id, final result, error flag) and returns a human-readable line to
+// append, or `undefined` when the event contributes nothing to the transcript body.
+export function renderEvent(event, state) {
+    if (!isRecord(event))
+        return;
+    captureSessionId(event, state);
+    switch (event.type) {
+        case "system":
+            return event.subtype === "init" ? `[init] session ${asString(event.session_id)}` : undefined;
+        case "assistant":
+            return renderMessageContent(event);
+        case "user":
+            return renderMessageContent(event);
+        case "result":
+            captureResult(event, state);
+            return undefined;
+        case "unparsed":
+            return asString(event.raw);
+        default:
+            return undefined;
+    }
+}
+function captureSessionId(event, state) {
+    const id = asString(event.session_id);
+    if (id)
+        state.sessionId = id;
+}
+function captureResult(event, state) {
+    state.isError = event.is_error === true;
+    const result = asString(event.result);
+    if (result !== undefined)
+        state.result = result;
+}
+function renderMessageContent(event) {
+    const message = event.message;
+    if (!isRecord(message) || !Array.isArray(message.content))
+        return;
+    const parts = [];
+    for (const block of message.content) {
+        const rendered = renderBlock(block);
+        if (rendered)
+            parts.push(rendered);
+    }
+    return parts.length > 0 ? parts.join("\n") : undefined;
+}
+function renderBlock(block) {
+    if (!isRecord(block))
+        return;
+    switch (block.type) {
+        case "text":
+            return asString(block.text);
+        case "tool_use":
+            return `[tool: ${asString(block.name) ?? "?"}] ${compactJson(block.input)}`;
+        case "tool_result":
+            return `[tool result] ${truncate(renderToolResult(block.content), 500)}`;
+        default:
+            return undefined;
+    }
+}
+function renderToolResult(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content.map((block) => (isRecord(block) ? (asString(block.text) ?? "") : "")).join("");
+    }
+    return compactJson(content);
+}
+function failureMessage(outcome) {
+    const stderr = outcome.stderr.trim();
+    return stderr || `claude exited with code ${outcome.exitCode ?? "unknown"}`;
+}
+// --- Shared helpers ---
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function compactJson(value) {
+    try {
+        return truncate(JSON.stringify(value) ?? "", 500);
+    }
+    catch {
+        return "";
+    }
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

package/dist/session-file.d.ts

@@ -0,0 +1,31 @@
+export interface SessionFrontmatter {
+    status: "running" | "succeeded" | "failed";
+    protocol: string | null;
+    ticket: string | null;
+    model: string | null;
+    sessionId: string | null;
+    command: string;
+    startedAt: string;
+    endedAt: string | null;
+    exitReason: string | null;
+}
+export declare const RESULT_MARKER = "\n---- Result ----\n";
+export declare function assertPlansGate(cwd: string): string | undefined;
+export declare function resolveSessionFilePath(cwd: string, ticket: string | undefined, now: Date, fileExists?: (path: string) => boolean): string;
+export declare function writeInitialSessionFile(sessionFilePath: string, frontmatter: SessionFrontmatter): void;
+export interface CompletionUpdate {
+    status: "succeeded" | "failed";
+    endedAt: string;
+    exitReason: "completed" | "error" | "terminated";
+    sessionId: string | null;
+    result: string;
+}
+export declare function applyCompletion(sessionFilePath: string, update: CompletionUpdate): void;
+export declare function appendTranscript(sessionFilePath: string, text: string): void;
+export interface SessionCompletion {
+    frontmatter: SessionFrontmatter;
+    result: string | undefined;
+}
+export declare function readCompletion(sessionFilePath: string): SessionCompletion;
+export declare function serializeFrontmatter(frontmatter: SessionFrontmatter): string;
+export declare function parseFrontmatter(block: string): SessionFrontmatter;

package/dist/session-file.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const RESULT_MARKER = "\n---- Result ----\n";
+// The CWD must be an AlignFirst-managed project (a `.plans/` dir marks it). Returns an error message
+// when the gate fails, `undefined` when it passes. `--guide`/`--help` bypass this.
+export function assertPlansGate(cwd) {
+    if (existsSync(join(cwd, ".plans")))
+        return;
+    return ("Error: no `.plans/` directory found in the current directory. " +
+        "Run alcode from the root of an AlignFirst-managed project.");
+}
+export function resolveSessionFilePath(cwd, ticket, now, fileExists = existsSync) {
+    const dir = ticket
+        ? join(cwd, ".plans", ticket, "coding-sessions")
+        : join(cwd, ".plans", "_coding-sessions");
+    const stamp = formatStamp(now);
+    let candidate = join(dir, `${stamp}.md`);
+    let suffix = 2;
+    while (fileExists(candidate)) {
+        candidate = join(dir, `${stamp}-${suffix}.md`);
+        ++suffix;
+    }
+    return candidate;
+}
+// Writes the initial `running` header. Present before the run starts so an interrupted run still
+// leaves an auditable record; the terminal frontmatter rewrite happens on completion.
+export function writeInitialSessionFile(sessionFilePath, frontmatter) {
+    const header = `${serializeFrontmatter(frontmatter)}\n`;
+    mkdirSync(dirname(sessionFilePath), { recursive: true });
+    writeFileSync(sessionFilePath, header);
+}
+// Appends the result block, then rewrites the frontmatter in place. Append-first keeps the tailed
+// transcript intact until the single terminal rewrite.
+export function applyCompletion(sessionFilePath, update) {
+    const content = readFileSync(sessionFilePath, "utf-8");
+    const { frontmatter, body } = splitSessionFile(content);
+    const updated = {
+        ...frontmatter,
+        status: update.status,
+        endedAt: update.endedAt,
+        exitReason: update.exitReason,
+        sessionId: update.sessionId ?? frontmatter.sessionId,
+    };
+    const resultBlock = `${RESULT_MARKER}\n${update.result}\n`;
+    writeFileSync(sessionFilePath, `${serializeFrontmatter(updated)}\n${body}${resultBlock}`);
+}
+export function appendTranscript(sessionFilePath, text) {
+    writeFileSync(sessionFilePath, text, { flag: "a" });
+}
+// Reads back a completed (or in-progress) session file — the durable result handoff a waking
+// OpenClaw agent or a human reads: frontmatter status/sessionId plus the `---- Result ----` block.
+export function readCompletion(sessionFilePath) {
+    const content = readFileSync(sessionFilePath, "utf-8");
+    const { frontmatter } = splitSessionFile(content);
+    // `lastIndexOf`, not `indexOf`: `applyCompletion` always appends the real result block last, so a
+    // `---- Result ----` echoed earlier in the transcript body (e.g. the agent printing a session
+    // file) must not truncate the actual result.
+    const markerIndex = content.lastIndexOf(RESULT_MARKER);
+    const result = markerIndex === -1 ? undefined : content.slice(markerIndex + RESULT_MARKER.length).trim();
+    return { frontmatter, result };
+}
+// --- Frontmatter serialization (dependency-free, round-trips with parseFrontmatter) ---
+export function serializeFrontmatter(frontmatter) {
+    const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${serializeValue(value)}`);
+    return `---\n${lines.join("\n")}\n---\n`;
+}
+function serializeValue(value) {
+    if (value === null)
+        return "";
+    return needsQuote(value) ? JSON.stringify(value) : value;
+}
+function needsQuote(value) {
+    return value === "" || /[:"#]/.test(value) || value !== value.trim();
+}
+function splitSessionFile(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match)
+        throw new Error("Session file is missing its frontmatter block.");
+    return { frontmatter: parseFrontmatter(match[1]), body: content.slice(match[0].length) };
+}
+export function parseFrontmatter(block) {
+    const map = {};
+    for (const line of block.split("\n")) {
+        const index = line.indexOf(":");
+        if (index === -1)
+            continue;
+        const key = line.slice(0, index).trim();
+        map[key] = parseValue(line.slice(index + 1).trim());
+    }
+    return {
+        status: map.status ?? "running",
+        protocol: map.protocol ?? null,
+        ticket: map.ticket ?? null,
+        model: map.model ?? null,
+        sessionId: map.sessionId ?? null,
+        command: map.command ?? "",
+        startedAt: map.startedAt ?? "",
+        endedAt: map.endedAt ?? null,
+        exitReason: map.exitReason ?? null,
+    };
+}
+function parseValue(raw) {
+    if (raw === "")
+        return null;
+    if (!raw.startsWith('"'))
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // A partially-written or hand-edited file may hold an unterminated/invalid quoted value; fall
+        // back to the raw text so the session file stays readable and sealable instead of crashing.
+        return raw;
+    }
+}
+// Local `YYYYMMDD-HHMMSS`.
+function formatStamp(now) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `${date}-${time}`;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@paleo/alcode",
+  "version": "0.1.0",
+  "license": "CC0-1.0",
+  "author": "Thomas MUR",
+  "description": "Run a coding agent through AlignFirst protocols, with a durable session file per run.",
+  "keywords": [
+    "ai",
+    "agent",
+    "alignfirst",
+    "cli",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paleo/alignfirst.git",
+    "directory": "packages/alcode"
+  },
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "packageManager": "npm@11.12.1",
+  "type": "module",
+  "bin": {
+    "alcode": "bin/alcode.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clear": "rimraf dist/*",
+    "lint": "biome check",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.4",
+    "rimraf": "~6.1.3",
+    "typescript": "~6.0.3",
+    "vitest": "~4.1.7"
+  }
+}

package/templates/guide-run-generic.md

@@ -0,0 +1,3 @@
+Use your platform's background-execution facility; do not detach `alcode` with `&` or a detach wrapper.
+
+Running under OpenClaw? Read `alcode --openclaw-guide` instead. It is the same manual with the OpenClaw-specific run instructions.

package/templates/guide-run-openclaw.md

@@ -0,0 +1,4 @@
+Under OpenClaw, background it through the `exec` tool:
+
+- Pass `background: true` and `timeout: 0` (no kill timer). Never rely on the auto-yield or a finite timeout.
+- Set the exec `workdir` to the project root as an **absolute** path (`~` is not expanded there), or `cd` into the project inside the command itself.

package/templates/guide-wake-generic.md

@@ -0,0 +1 @@
+When your platform tells you the backgrounded `alcode` exited, do exactly this:

package/templates/guide-wake-openclaw.md

@@ -0,0 +1 @@
+OpenClaw wakes this session when the backgrounded `alcode` exits. The wake may arrive as a **plain heartbeat poll with no message text**. Do not wait for an explicit "exec finished" notice. Whenever you are woken, or receive any heartbeat, while an `alcode` run is pending, do exactly this:

package/templates/guide.md

@@ -0,0 +1,100 @@
+# AlignFirst Delegation Guide{{TITLE-SUFFIX}}
+
+Run a coding agent through AlignFirst protocols with the `alcode` CLI. It wraps a coding-agent CLI for non-interactive use: it invokes a protocol, streams the run to a session file, and returns the result.
+
+**Never implement, investigate, or modify the codebase yourself while delegating. Your role is to delegate and guide the agent.**
+
+Run `alcode` from the root of the target project, so the agent works in the right repo. The project must contain a `.plans/` directory.
+
+## How it runs
+
+`alcode` runs the coding agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout as it arrives. It never backgrounds or detaches itself.
+
+Coding runs can be long (several hours is fine): **always run `alcode` as a background task**, so you stay free while it works. The backgrounding is **your platform's** job, never alcode's own.
+
+{{RUN}}
+
+As soon as the run is backgrounded, tell the user the coding agent is now working in the background and that you will report back when it finishes (e.g. *"Le coding agent tourne en arrière-plan — je te préviens dès que c'est terminé."*). Then go available. Do **not** poll.
+
+Every run writes a session file under `.plans/`: `.plans/<ticket>/coding-sessions/<stamp>.md`, or `.plans/_coding-sessions/<stamp>.md` without a ticket. This file is the durable record of the run. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
+
+## After a background run completes
+
+{{WAKE}}
+
+1. **Read the run's session file** (the path `alcode` printed on its first line, under `coding-sessions/`). Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome.
+2. **Report the outcome to the user** where the work was requested. Send one concise message: succeeded or failed, plus a one-line summary of the result for the audience.
+3. Do **not** re-verify the repo, re-run the coding agent, fetch/merge branches, or inspect `git`. The coding agent already did the work and the session file is authoritative. Relay its outcome, nothing more.
+
+If the session file says the run failed, report that plainly and propose the next step; don't silently retry.
+
+## CLI reference
+
+```
+alcode --new --protocol <protocol> --ticket <id> [--message "..."]
+alcode --new --message "..."
+alcode --resume <sessionId> [--protocol <protocol>] [--message "..."]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--new` | Start a new session. |
+| `--resume <id>` | Continue an existing session. |
+| `--protocol <p>` | One of `spec`, `plan`, `aad`, `description`, `read`, `review`, `merge`. Optional. |
+| `--ticket <id>` | Ticket ID. Required with `--new` + `--protocol`. |
+| `--message "..."` | Message to send. Required for `spec`, `aad`, and when no `--protocol`. |
+| `--model <model>` | Model override. |
+
+For `--new` runs, the `Session ID:` is printed to stdout and written to the session file frontmatter (the durable source of truth). Save it to resume the conversation later.
+
+**No protocol:** the message is sent as-is (no AlignFirst command). Use it to answer the agent's questions in an existing session, execute a plan in a new session, or ask a question:
+
+```bash
+alcode --resume <sessionId> --message "Your answer"
+alcode --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"
+```
+
+When asking a question (not executing a plan) with `--new` and no protocol, the agent will try to implement by default. End the message with a constraint: *"Do not implement anything. We need to talk first."*
+
+## Spec-Plan-Execute workflow
+
+The default workflow. Always start with it, except for very insignificant tasks.
+
+1. **Spec** — `alcode --new --protocol spec --ticket AB-123 --message "Feature description"`. The agent investigates and asks questions; save the session id. Iterate until it writes the spec file.
+2. **Plan** — `alcode --resume <sessionId> --protocol plan`. The agent writes the plan file.
+3. **Execute** — `alcode --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"`. The agent implements and writes a summary file.
+4. **Commit** — use the suggested commit message from the spec file.
+
+## Light workflow (AAD)
+
+For one-shot changes or follow-up adjustments right after executing a plan. The agent investigates, discusses, then implements in one session.
+
+```bash
+alcode --new --protocol aad --ticket AB-123 --message "Task description"
+```
+
+Answer questions as in the spec flow. The agent implements and writes a summary file, which carries a suggested commit message.
+
+## Other protocols
+
+- **description** — `alcode --new --protocol description --ticket AB-123`. Writes a PR/MR description for committed work. No discussion.
+- **read** — `alcode --new --protocol read --ticket AB-123 [--message "..."]`. Loads the ticket's spec and summary files into context; with a message, answers it against that context.
+- **review** — `alcode --new --protocol review --ticket AB-123`. Reviews the current branch against the base and writes a review file.
+- **merge** — `alcode --new --protocol merge --ticket AB-123`. Resolves conflicts and summarizes tricky resolutions. Pass the incoming branch via `--message` to start the merge.
+
+## Answering agent questions
+
+During spec and AAD sessions the agent asks questions before proceeding. Resume **without a protocol** to answer. Answer all questions in one message, numbered to match:
+
+```bash
+alcode --resume <sessionId> --message \
+  "1 - Explore the codebase and give me your opinion.
+2 - Is that a good design? We need the cleanest code possible.
+3 - Yes, it should be optional."
+```
+
+**Technical questions** — architecture, patterns, existing behavior, anything answerable by reading the code. Never escalate these to the user. Push the agent to investigate: *"Explore the codebase to find out, and give me your opinion."*, *"Do not rush. Take the time to fully understand the situation first."*, *"What would be the most elegant way to do it?"*, *"Check if a similar pattern is already implemented elsewhere in the codebase."*
+
+**Functional or UX questions** — product behavior, user-facing decisions, business rules. These need human judgement: escalate to your user, then relay the answer.
+
+When in doubt, ask the agent to explore first. Escalate only when the question truly cannot be answered from the codebase.