@paleo/alcode 0.5.2 → 0.6.0

package/README.md

@@ -12,6 +12,8 @@ Coding runs can be very long: the caller always runs `alcode` as a background ta
 
 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.
 
+When the coding agent's own session on the host is missing or expired, `alcode` detects the `authentication_failed` signal in its stream, seals the session file with `exitReason: auth_required`, and exits `2` (distinct from `1`) with a one-line stderr message.
+
 ## Usage
 
 ```bash

package/dist/cli.js

@@ -5,6 +5,9 @@ import { renderGuide } from "./guide.js";
 import { assertPlansGate, listSessionRecords, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
 import { buildPrompt, PROTOCOLS } from "./prompt.js";
 import { runClaude } from "./run-claude.js";
+// Distinct from 1 (ordinary run failure) so a script can branch on an auth failure that needs an
+// operator re-login rather than a retry.
+const EXIT_AUTH_REQUIRED = 2;
 export async function main(options) {
     const argv = options?.argv ?? process.argv;
     const stdout = options?.stdout ?? process.stdout;
@@ -73,6 +76,11 @@ async function runSession(parsed, ctx) {
     if (parsed.isNew && result.sessionId) {
         stdout.write(`\nSession ID: ${result.sessionId}\n`);
     }
+    if (result.authRequired) {
+        stderr.write("alcode: coding agent not authenticated — an administrator must re-login on the host " +
+            "(`claude`, then `/login`).\n");
+        return EXIT_AUTH_REQUIRED;
+    }
     return result.status === "succeeded" ? 0 : 1;
 }
 // Fail-fast launch guards, run against the (healed) session records before anything is written.

package/dist/run-claude.d.ts

@@ -15,6 +15,7 @@ export interface RunOutput {
 }
 export interface RunResult {
     status: "succeeded" | "failed";
+    authRequired: boolean;
     sessionId: string | null;
     result: string;
 }
@@ -26,6 +27,7 @@ export interface StreamState {
     sessionId?: string;
     result?: string;
     isError: boolean;
+    authFailed: boolean;
 }
 export declare function createStreamState(): StreamState;
 export declare function parseEventLine(line: string): unknown;

package/dist/run-claude.js

@@ -11,15 +11,25 @@ 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);
+    // An auth signal only matters when the run actually failed: claude retries a 401, so a signal it
+    // recovered from (run still succeeded) is not a problem to report.
+    const authRequired = failed && state.authFailed;
+    const result = authRequired
+        ? authFailureMessage(state.result)
+        : (state.result ?? failureMessage(outcome));
     applyCompletion(config.sessionFilePath, {
         status: failed ? "failed" : "succeeded",
         endedAt: new Date().toISOString(),
-        exitReason: failed ? "error" : "completed",
+        exitReason: authRequired ? "auth_required" : failed ? "error" : "completed",
         sessionId: state.sessionId ?? null,
         result,
     });
-    return { status: failed ? "failed" : "succeeded", sessionId: state.sessionId ?? null, result };
+    return {
+        status: failed ? "failed" : "succeeded",
+        authRequired,
+        sessionId: state.sessionId ?? null,
+        result,
+    };
 }
 function spawnClaude(config, state, out) {
     const child = spawn("claude", buildClaudeArgs(config), {
@@ -167,7 +177,7 @@ function emitEvent(sessionFilePath, line, state, out) {
     out.write(`${rendered}\n`);
 }
 export function createStreamState() {
-    return { isError: false };
+    return { isError: false, authFailed: false };
 }
 export function parseEventLine(line) {
     try {
@@ -183,6 +193,7 @@ export function renderEvent(event, state) {
     if (!isRecord(event))
         return;
     captureSessionId(event, state);
+    captureAuthFailure(event, state);
     switch (event.type) {
         case "system":
             return event.subtype === "init" ? `[init] session ${asString(event.session_id)}` : undefined;
@@ -204,6 +215,10 @@ function captureSessionId(event, state) {
     if (id)
         state.sessionId = id;
 }
+function captureAuthFailure(event, state) {
+    if (event.error === "authentication_failed")
+        state.authFailed = true;
+}
 function captureResult(event, state) {
     state.isError = event.is_error === true;
     const result = asString(event.result);
@@ -248,6 +263,15 @@ function failureMessage(outcome) {
     const stderr = outcome.stderr.trim();
     return stderr || `claude exited with code ${outcome.exitCode ?? "unknown"}`;
 }
+// The remedy is an operator action on the host, not a retry — so the result block names it and
+// keeps claude's own reason line (e.g. "OAuth session expired…") beneath it.
+function authFailureMessage(claudeReason) {
+    const base = "Coding agent not authenticated (authentication_failed): the host session is missing, expired, " +
+        "or rejected. An administrator must re-login on the host (run `claude`, then `/login`) before " +
+        "alcode can run again.";
+    const detail = claudeReason?.trim();
+    return detail ? `${base}\n\n${detail}` : base;
+}
 // --- Shared helpers ---
 function isRecord(value) {
     return typeof value === "object" && value !== null;

package/dist/session-file.d.ts

@@ -19,7 +19,7 @@ export declare function writeInitialSessionFile(sessionFilePath: string, frontma
 export interface CompletionUpdate {
     status: "succeeded" | "failed";
     endedAt: string;
-    exitReason: "completed" | "error" | "terminated";
+    exitReason: "completed" | "error" | "terminated" | "auth_required";
     sessionId: string | null;
     result: string;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
-  "description": "Run a coding agent through AlignFirst protocols, with a durable session file per run.",
+  "description": "Run a coding agent through AlignFirst protocols.",
   "keywords": [
     "ai",
     "agent",

package/templates/cli-reference.md

@@ -35,7 +35,7 @@ For large work, do not rush. Decompose it yourself only when the concerns are tr
 
 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.
+3. **Execute** — `alcode --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"`. The agent implements and writes a summary file. When executing a main plan that spans several sub-plans and the working tree is clean, append to the message: *"Feel free to commit between each plan."*
 4. **Commit** — use the suggested commit message from the spec file.
 
 ## Light workflow (AAD)

package/templates/generic-guide.md

@@ -14,6 +14,8 @@ Running under OpenClaw? Read `alcode --openclaw-guide` instead — the same manu
 
 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.
 
+An `exitReason` of `auth_required` in the frontmatter (alcode also exits `2`) means the coding agent is not authenticated on the host: an administrator must re-login there before any run can succeed. Report that and do not retry.
+
 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/openclaw-guide.md

@@ -21,7 +21,7 @@ Under OpenClaw, background it through the `exec` tool:
 - 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."*). On Discord this "started" ack, like every user-facing post in the thread, is a `message` `action: "thread-reply"` carrying the thread's `threadId` — free-form assistant text streams to the parent channel, not the thread, so never emit this ack as plain prose. Then go available. Do **not** poll.
+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."*). Deliver this "started" ack exactly like the completion report below: if you set `--meta` (a Discord thread you created this turn), the ack is a `message` `action: "thread-reply"` carrying that thread's `threadId` — your free-form text would stream to the parent channel. In every other case — always on Slack, and on a thread-bound Discord session — the ack is your plain text; do **not** also post it via `message`, that double-posts. 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.
 
@@ -45,4 +45,6 @@ Any heartbeat received while an `alcode` run is **still pending** (running, or f
 
 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.
 
+If the frontmatter's `exitReason` is `auth_required`, the coding agent itself is not authenticated on the host (its session is missing or expired). No run can succeed until an administrator re-logs it in on the host. Tell the user exactly that, and do not retry — a retry hits the same wall.
+
 {{CLI_REFERENCE}}