@paleo/alcode 0.4.1 → 0.5.1

package/README.md

@@ -8,7 +8,7 @@ Run `alcode --guide` for the full delegation guide. When an OpenClaw agent is th
 
 `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.
+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`, chaining `openclaw system event --mode now --session-key <key>` onto the command as prescribed by the guide; that immediate wake fires when the run finishes, and the woken agent 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.
 

package/dist/cli.d.ts

@@ -9,6 +9,7 @@ export interface MainOptions {
 }
 export declare function main(options?: MainOptions): Promise<number>;
 export declare function checkLaunchGuards(parsed: AlcodeArgs, realCwd: string, records: SessionRecord[]): string | undefined;
+export declare function resolveTicket(parsed: AlcodeArgs, 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

@@ -58,14 +58,16 @@ async function runSession(parsed, ctx) {
         return 1;
     }
     const realCwd = realpathSync(cwd);
-    const guardError = checkLaunchGuards(parsed, realCwd, listSessionRecords(cwd));
+    const records = listSessionRecords(cwd);
+    const guardError = checkLaunchGuards(parsed, realCwd, records);
     if (guardError) {
         stderr.write(`${guardError}\n`);
         return 1;
     }
     const now = new Date();
-    const sessionFilePath = resolveSessionFilePath(cwd, parsed.ticket, now);
-    writeInitialSessionFile(sessionFilePath, buildFrontmatter(parsed, now, realCwd));
+    const ticket = resolveTicket(parsed, records);
+    const sessionFilePath = resolveSessionFilePath(cwd, ticket, now);
+    writeInitialSessionFile(sessionFilePath, buildFrontmatter(parsed, now, realCwd, ticket));
     stdout.write(`Session file: ${relative(cwd, sessionFilePath)}\n\n`);
     const result = await runClaude(buildRunConfig(parsed, cwd, sessionFilePath, env), stdout);
     if (parsed.isNew && result.sessionId) {
@@ -110,11 +112,43 @@ function unknownResumeError(resume, records) {
     });
     return `Error: unknown session id ${resume}. Known recent sessions:\n${recent.join("\n")}`;
 }
-function buildFrontmatter(parsed, now, realCwd) {
+// The effective ticket scopes the session file to `.plans/<ticket>/_alcode/` and lands in the
+// frontmatter. Exported for tests. Precedence: explicit `--ticket`, then the resumed session's
+// records, then a `.plans/<ticket>/` path in the message.
+export function resolveTicket(parsed, records) {
+    if (parsed.ticket !== undefined)
+        return parsed.ticket;
+    if (parsed.resume !== undefined)
+        return inheritTicketFromResume(parsed.resume, records);
+    if (parsed.isNew && parsed.message !== undefined)
+        return inferTicketFromMessage(parsed.message);
+    return;
+}
+// Latest record of the resumed session that carries a ticket — the resumed run keeps writing
+// under the same ticket directory, and its frontmatter keeps the ticket for later resumes.
+function inheritTicketFromResume(resume, records) {
+    const ticketed = records.filter((r) => r.frontmatter.sessionId === resume && r.frontmatter.ticket !== null);
+    const latest = ticketed.sort((a, b) => b.frontmatter.startedAt.localeCompare(a.frontmatter.startedAt))[0];
+    return latest?.frontmatter.ticket ?? undefined;
+}
+// A message like `Execute the plan: .plans/2/B2-plan.md` names its ticket. `_`-prefixed segments
+// (e.g. `_alcode`) are not tickets; several distinct candidates mean the message is ambiguous.
+function inferTicketFromMessage(message) {
+    const candidates = new Set();
+    for (const match of message.matchAll(/\.plans\/([A-Za-z0-9._-]+)\//g)) {
+        const segment = match[1];
+        if (!segment.startsWith("_") && isPathSafeTicket(segment))
+            candidates.add(segment);
+    }
+    if (candidates.size !== 1)
+        return;
+    return [...candidates][0];
+}
+function buildFrontmatter(parsed, now, realCwd, ticket) {
     return {
         status: "running",
         protocol: parsed.protocol ?? null,
-        ticket: parsed.ticket ?? null,
+        ticket: ticket ?? null,
         model: parsed.model ?? null,
         sessionId: null,
         command: formatCommand(parsed),
@@ -207,9 +241,6 @@ export function validateArgs(args) {
     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 '..'.");

package/dist/guide.js

@@ -1,13 +1,12 @@
 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
+// Each variant owns a full guide (templates/<variant>-guide.md) carrying its own
+// platform-specific prose. Two shared blocks fill the tags common to every variant:
+//   {{INTRODUCTION}}  — what alcode is and how to invoke it
+//   {{CLI_REFERENCE}} — the CLI reference and the protocol workflows below it
 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())
+    return readTemplate(`${variant}-guide.md`)
+        .replaceAll("{{INTRODUCTION}}", readTemplate("introduction.md").trimEnd())
+        .replaceAll("{{CLI_REFERENCE}}", readTemplate("cli-reference.md").trimEnd())
         .trimEnd();
 }
 function readTemplate(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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.md → cli-reference.md}

@@ -1,35 +1,3 @@
-# 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>/_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 `_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. When a session turns bad, keep everything in place — session files, directories, and records are the durable audit trail; never delete them; just start a new session.
-
 ## CLI reference
 
 ```
@@ -44,7 +12,7 @@ alcode --resume <sessionId> [--protocol <protocol>] [--message "..."]
 | `--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`. |
+| `--message "..."` | Message to send, written in English. Required for `spec`, `aad`, and when no `--protocol`. |
 | `--model <model>` | Model override. |
 | `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `alcode` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
 
@@ -89,7 +57,7 @@ Answer questions as in the spec flow. The agent implements and writes a summary
 
 ## 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:
+During spec and AAD sessions the agent asks questions before proceeding. Resume **without a protocol** to answer. Compose the answers in English, all questions in one message, numbered to match:
 
 ```bash
 alcode --resume <sessionId> --message \

package/templates/generic-guide.md

@@ -0,0 +1,19 @@
+# AlignFirst Delegation Guide
+
+{{INTRODUCTION}}
+
+## How it runs
+
+`alcode` runs the coding agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout and to a session file under `.plans/`. It never backgrounds or detaches itself.
+
+Coding runs can be long (several hours is fine): background `alcode` with your platform's own background-execution facility — never detach it with `&` or a detach wrapper. **One protocol run at a time per worktree**; plain messages can be sent at any time.
+
+Running under OpenClaw? Read `alcode --openclaw-guide` instead — the same manual with the OpenClaw-specific run and wake instructions.
+
+## After a run completes
+
+Read the run's session file (the path `alcode` prints on its first line, under `_alcode/`): its frontmatter carries `status` (`succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome. Report it to the user where the work was requested. If the run failed, say so plainly and propose the next step.
+
+Do **not** re-verify the repo, re-run the agent, or inspect `git` — the session file is authoritative. Keep session files in place; they are the durable audit trail.
+
+{{CLI_REFERENCE}}

package/templates/introduction.md

@@ -0,0 +1,5 @@
+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.

package/templates/openclaw-guide.md

@@ -0,0 +1,48 @@
+# AlignFirst Delegation Guide (OpenClaw)
+
+{{INTRODUCTION}}
+
+## 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.
+
+Under OpenClaw, background it through the `exec` tool:
+
+- Before the first `alcode` run of this session, call the `session_status` tool and read the `Session:` line from its result — that is this session's key. Obtain it once, reuse it for every run of this session.
+- The exec command chains a completion wake onto the run:
+
+  `alcode <flags> ; openclaw system event --text "alcode run finished — read its session file and report to the user" --mode now --session-key <KEY>`
+
+  Chain with `;` (never `&&`) so a failed run wakes you too. The wake may reach you as a bare heartbeat with the text dropped, and OpenClaw's own `Exec completed` notice may lag behind it — never wait for either text.
+- 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.
+- `--meta` is for one case only: a **Discord** thread **you created yourself** this turn via `message` `action: "thread-create"`. There, the completion wake's plain reply would go to the channel, so add `--meta "<THREAD_ID>"` with that thread's `chat_id`; the wake then reports back into the thread via `message` `action: "thread-reply"`. In **every other case — always on Slack, and on Discord when the session is already thread-bound — omit `--meta`.** Slack auto-threads plain replies and exposes no `send`/`thread-reply` action, so a `--meta` there makes the wake attempt an unsupported `message` send that fails; a thread-bound session already replies in its own thread.
+
+As soon as the run is backgrounded, tell the user — in the user's language — that the coding agent is now working in the background and that you will report back when it finishes (e.g. *"The coding agent is running in the background — I'll let you know as soon as it's done."*). Then go available. Do **not** poll.
+
+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
+
+The chained wake fires when the backgrounded `alcode` exits: this session receives a heartbeat, usually as a plain heartbeat poll with no message text (the wake text is often dropped in transit). A run counts as pending while it is running **and until its outcome is reported**.
+
+**First, decide whether this heartbeat needs a report.** A heartbeat is the completion wake only while a run is pending. Once you have already reported a run's outcome, later heartbeats for it — a single run can wake you more than once, since the platform's own exec-exit notice may fire on top of the chained wake — need nothing: end the turn with a final answer of exactly `NO_REPLY`. Never `HEARTBEAT_OK`: it is not swallowed, it posts as literal text where the user reads. Whenever a heartbeat turn has nothing new to say, the answer is `NO_REPLY`, never `HEARTBEAT_OK`.
+
+Any heartbeat received while an `alcode` run is **still pending** (running, or finished but not yet reported) is the completion wake — do exactly this:
+
+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. Two cases:
+   - The frontmatter `meta` carries a destination (a Discord thread target): send the report there with `message` `action: "thread-reply"` (never `action: "send"`), then end the wake turn with a final answer of exactly `NO_REPLY` — any other final text streams to the channel as a stray duplicate.
+   - No `meta` destination (always the case on Slack, and on a thread-bound Discord session): the work was requested on this session's own surface, so **the report itself is your plain-text final reply** — just write it, no `message` tool. On Slack it auto-threads back to the right thread. Never end such a wake turn silently.
+
+   A wake turn ends with the report or with exactly `NO_REPLY` — nothing else, ever, and never `HEARTBEAT_OK`. `NO_REPLY` is the ending after a `message`-tool report (the report is already delivered) and for any wake with nothing new to report.
+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. When a session turns bad, keep everything in place — session files, directories, and records are the durable audit trail; never delete them; just start a new session.
+
+{{CLI_REFERENCE}}

package/templates/guide-run-generic.md

@@ -1,3 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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-wake-generic.md

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

package/templates/guide-wake-openclaw.md

@@ -1 +0,0 @@
-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: