@paleo/alcode 0.5.3 → 0.7.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,6 +1,6 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "Run a coding agent through AlignFirst protocols.",

package/templates/cli-reference.md

@@ -48,11 +48,20 @@ 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.
 
+## Review workflow
+
+Two fresh sessions: one reviews, one fixes.
+
+1. **Review** — `alcode --new --protocol review --ticket AB-123`. The agent reviews the current branch against the base branch and writes a review file; its path is in the run's result. The base defaults to the repository's default branch; override it via `--message "Base branch: \`develop\`"`.
+2. **Fix** (optional) — `alcode --new --protocol aad --ticket AB-123 --message "Here is a code review: \`.plans/AB-123/B1-review.md\`. What should we fix?"` (adapt the path). The agent proposes fixes; decide together what to fix, as in any AAD session, then it implements and writes a summary file.
+
+Skip the fix step when the review is informational.
+
 ## 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.
+- **review** — see the review workflow above.
 - **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

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

@@ -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}}