@paleo/alcode 0.3.0 → 0.4.0

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import { type SessionRecord } from "./session-file.js";
 import { type RunConfig, type RunOutput } from "./run-claude.js";
 export interface MainOptions {
     argv?: string[];
@@ -7,6 +8,7 @@ export interface MainOptions {
     env?: NodeJS.ProcessEnv;
 }
 export declare function main(options?: MainOptions): Promise<number>;
+export declare function checkLaunchGuards(parsed: AlcodeArgs, realCwd: string, records: SessionRecord[]): string | undefined;
 export declare function buildRunConfig(parsed: AlcodeArgs, cwd: string, sessionFilePath: string, env: NodeJS.ProcessEnv): RunConfig;
 export interface AlcodeArgs {
     isNew: boolean;

package/dist/cli.js

@@ -1,8 +1,8 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { relative } from "node:path";
 import { parseArgs } from "node:util";
 import { renderGuide } from "./guide.js";
-import { assertPlansGate, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
+import { assertPlansGate, listSessionRecords, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
 import { buildPrompt, PROTOCOLS } from "./prompt.js";
 import { runClaude } from "./run-claude.js";
 export async function main(options) {
@@ -57,9 +57,15 @@ async function runSession(parsed, ctx) {
         stderr.write(`${gateError}\n`);
         return 1;
     }
+    const realCwd = realpathSync(cwd);
+    const guardError = checkLaunchGuards(parsed, realCwd, listSessionRecords(cwd));
+    if (guardError) {
+        stderr.write(`${guardError}\n`);
+        return 1;
+    }
     const now = new Date();
     const sessionFilePath = resolveSessionFilePath(cwd, parsed.ticket, now);
-    writeInitialSessionFile(sessionFilePath, buildFrontmatter(parsed, now));
+    writeInitialSessionFile(sessionFilePath, buildFrontmatter(parsed, now, realCwd));
     stdout.write(`Session file: ${relative(cwd, sessionFilePath)}\n\n`);
     const result = await runClaude(buildRunConfig(parsed, cwd, sessionFilePath, env), stdout);
     if (parsed.isNew && result.sessionId) {
@@ -67,7 +73,44 @@ async function runSession(parsed, ctx) {
     }
     return result.status === "succeeded" ? 0 : 1;
 }
-function buildFrontmatter(parsed, now) {
+// Fail-fast launch guards, run against the (healed) session records before anything is written.
+// Returns the error to print, or `undefined` when the launch may proceed.
+export function checkLaunchGuards(parsed, realCwd, records) {
+    if (parsed.resume !== undefined) {
+        // A resumed run writes a new session file carrying the same sessionId as the original, so one
+        // id can match several records — a running status on any of them blocks.
+        const matches = records.filter((r) => r.frontmatter.sessionId === parsed.resume);
+        if (matches.length === 0)
+            return unknownResumeError(parsed.resume, records);
+        const running = matches.find((r) => r.frontmatter.status === "running");
+        if (running) {
+            return (`Error: session ${parsed.resume} is still running (pid ${running.frontmatter.pid}); ` +
+                "wait for it to finish or kill it.");
+        }
+    }
+    // Protocol runs only: plain messages (answers, questions, plan executions) may run at any time.
+    if (parsed.protocol !== undefined) {
+        const busy = records.find((r) => r.frontmatter.status === "running" && r.frontmatter.cwd === realCwd);
+        if (busy) {
+            return (`Error: a protocol run is already active in this worktree (${busy.path}, ` +
+                `pid ${busy.frontmatter.pid}); one protocol run at a time per worktree.`);
+        }
+    }
+    return;
+}
+function unknownResumeError(resume, records) {
+    if (records.length === 0) {
+        return `Error: unknown session id ${resume}; no session records exist under .plans/.`;
+    }
+    const recent = [...records]
+        .sort((a, b) => b.frontmatter.startedAt.localeCompare(a.frontmatter.startedAt))
+        .slice(0, 5)
+        .map(({ frontmatter: f }) => {
+        return `  ${f.sessionId ?? "(no id)"}  ${f.status}  ${f.startedAt}  ticket ${f.ticket ?? "-"}`;
+    });
+    return `Error: unknown session id ${resume}. Known recent sessions:\n${recent.join("\n")}`;
+}
+function buildFrontmatter(parsed, now, realCwd) {
     return {
         status: "running",
         protocol: parsed.protocol ?? null,
@@ -76,6 +119,8 @@ function buildFrontmatter(parsed, now) {
         sessionId: null,
         command: formatCommand(parsed),
         meta: parsed.meta ?? null,
+        pid: process.pid,
+        cwd: realCwd,
         startedAt: now.toISOString(),
         endedAt: null,
         exitReason: null,
@@ -171,7 +216,7 @@ export function validateArgs(args) {
     }
     return;
 }
-// The ticket becomes a `.plans/<ticket>/coding-sessions/…` path segment. Ticket formats vary by
+// The ticket becomes a `.plans/<ticket>/_alcode/…` 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) {

package/dist/session-file.d.ts

@@ -6,6 +6,8 @@ export interface SessionFrontmatter {
     sessionId: string | null;
     command: string;
     meta: string | null;
+    pid: number | null;
+    cwd: string | null;
     startedAt: string;
     endedAt: string | null;
     exitReason: string | null;
@@ -28,5 +30,10 @@ export interface SessionCompletion {
     result: string | undefined;
 }
 export declare function readCompletion(sessionFilePath: string): SessionCompletion;
+export interface SessionRecord {
+    path: string;
+    frontmatter: SessionFrontmatter;
+}
+export declare function listSessionRecords(cwd: string): SessionRecord[];
 export declare function serializeFrontmatter(frontmatter: SessionFrontmatter): string;
 export declare function parseFrontmatter(block: string): SessionFrontmatter;

package/dist/session-file.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, 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
@@ -10,9 +10,7 @@ export function assertPlansGate(cwd) {
         "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 dir = ticket ? join(cwd, ".plans", ticket, "_alcode") : join(cwd, ".plans", "_alcode");
     const stamp = formatStamp(now);
     let candidate = join(dir, `${stamp}.md`);
     let suffix = 2;
@@ -59,6 +57,79 @@ export function readCompletion(sessionFilePath) {
     const result = markerIndex === -1 ? undefined : content.slice(markerIndex + RESULT_MARKER.length).trim();
     return { frontmatter, result };
 }
+// Lists every session record for a project root: `.plans/_alcode/*.md` plus each ticket's
+// `.plans/<ticket>/_alcode/*.md`. The session files are the registry — no separate registry file.
+// Self-healing: a `running` record whose pid is gone is a stale leftover from an interrupted run;
+// it gets sealed in passing so the launch guards never block on dead state. The returned records
+// reflect the post-healing state.
+export function listSessionRecords(cwd) {
+    const plansDir = join(cwd, ".plans");
+    const sessionDirs = [join(plansDir, "_alcode")];
+    for (const entry of readEntries(plansDir)) {
+        if (entry.isDirectory() && entry.name !== "_alcode") {
+            sessionDirs.push(join(plansDir, entry.name, "_alcode"));
+        }
+    }
+    const records = [];
+    for (const dir of sessionDirs) {
+        for (const entry of readEntries(dir)) {
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            const path = join(dir, entry.name);
+            const frontmatter = readFrontmatterOrSkip(path);
+            if (frontmatter)
+                records.push({ path, frontmatter: sealIfStale(path, frontmatter) });
+        }
+    }
+    return records;
+}
+function readEntries(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+// A malformed file (e.g. missing its frontmatter block) must not block every future launch.
+function readFrontmatterOrSkip(path) {
+    try {
+        return readCompletion(path).frontmatter;
+    }
+    catch {
+        return;
+    }
+}
+function sealIfStale(path, frontmatter) {
+    if (frontmatter.status !== "running")
+        return frontmatter;
+    if (frontmatter.pid !== null && isPidAlive(frontmatter.pid))
+        return frontmatter;
+    const update = {
+        status: "failed",
+        endedAt: new Date().toISOString(),
+        exitReason: "terminated",
+        sessionId: frontmatter.sessionId,
+        result: `Sealed as interrupted: process ${frontmatter.pid ?? "(unknown)"} is gone.`,
+    };
+    applyCompletion(path, update);
+    return {
+        ...frontmatter,
+        status: update.status,
+        endedAt: update.endedAt,
+        exitReason: update.exitReason,
+    };
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: the process exists but belongs to another user — alive. ESRCH (or anything else): dead.
+        return err.code === "EPERM";
+    }
+}
 // --- Frontmatter serialization (dependency-free, round-trips with parseFrontmatter) ---
 export function serializeFrontmatter(frontmatter) {
     const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${serializeValue(value)}`);
@@ -67,6 +138,8 @@ export function serializeFrontmatter(frontmatter) {
 function serializeValue(value) {
     if (value === null)
         return "";
+    if (typeof value === "number")
+        return String(value);
     return needsQuote(value) ? JSON.stringify(value) : value;
 }
 function needsQuote(value) {
@@ -95,11 +168,19 @@ export function parseFrontmatter(block) {
         sessionId: map.sessionId ?? null,
         command: map.command ?? "",
         meta: map.meta ?? null,
+        pid: parsePid(map.pid),
+        cwd: map.cwd ?? null,
         startedAt: map.startedAt ?? "",
         endedAt: map.endedAt ?? null,
         exitReason: map.exitReason ?? null,
     };
 }
+function parsePid(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const pid = Number(raw);
+    return Number.isFinite(pid) ? pid : null;
+}
 function parseValue(raw) {
     if (raw === "")
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "Run a coding agent through AlignFirst protocols, with a durable session file per run.",

package/templates/guide-run-openclaw.md

@@ -2,4 +2,5 @@ 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.
+- The session-file path comes from the run's first stdout line (`Session file: …`), available via `process log <id>`. The stamp in the file name is the run's start time; it cannot be derived from the clock.
 - If the outcome must be reported into a thread **you created yourself** via `message` `action: "thread-create"`, add `--meta "<THREAD_ID>"` with that thread's `chat_id`: the completion wake's plain reply goes to this session's default surface (the channel), and only the session file's `meta` can point your report back at the thread (via `message` `action: "thread-reply"`). In every other case omit `--meta` — platform-threaded replies and thread-bound sessions already report in the right place.

package/templates/guide.md

@@ -16,17 +16,19 @@ Coding runs can be long (several hours is fine): **always run `alcode` as a back
 
 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.
+Every run writes a session file under `.plans/`: `.plans/<ticket>/_alcode/<stamp>.md`, or `.plans/_alcode/<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.
+
+**One protocol run at a time per workspace** — protocol runs share the working tree. Finish (or kill) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
 
 ## 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. If you set `meta` at launch, it is there too.
-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. If the frontmatter `meta` carries a destination (e.g. a thread target), route this report there — a plain reply from the wake turn goes to the session's default surface, which may not be where the work was requested.
+1. **Read the run's session file** (the path `alcode` printed on its first line, under `_alcode/`). Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome. If you set `meta` at launch, it is there too.
+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. If the frontmatter `meta` carries a destination (e.g. a thread target), route this report there — a plain reply from the wake turn goes to the session's default surface, which may not be where the work was requested. When the report went out through the `message` tool, end the wake turn with a final answer of exactly `NO_REPLY` — any other final text streams to the default surface as a stray duplicate. `NO_REPLY` is the only silent ending; never improvise another token (`HEARTBEAT_OK` posts as literal text).
 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.
+If the session file says the run failed, report that plainly and propose the next step; don't silently retry. When a session turns bad, keep everything in place — session files, directories, and records are the durable audit trail; never delete them.
 
 ## CLI reference
 
@@ -61,6 +63,8 @@ When asking a question (not executing a plan) with `--new` and no protocol, the
 
 The default workflow. Always start with it, except for very insignificant tasks.
 
+For large work, do not rush. Decompose it yourself only when the concerns are truly distinct; otherwise write one big spec, iterate on discussing it with the agent, then translate it into one or several plans.
+
 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.