@laskaridis/afk 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# afk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Leave a coding agent implementing a feature, one task at a time, while you are away from keyboard.
+
+`afk` is agent-neutral: it launches a fresh session of the coding agent you choose, hands it your instructions, reads the
+agent's final response, and repeats until the feature is reported complete, blocked, or the iteration limit is reached.
+
+Requires Node.js **22.13.0 or later**.
+
+## Install
+
+```sh
+npm install --global @laskaridis/afk
+```
+
+This installs the `afk` command. Install and authenticate a supported coding agent before running it.
+
+## Usage
+
+```
+afk [options] [prompt...]
+```
+
+The feature instructions come from the prompt arguments, `--prompt-file <path>`, or stdin.
+
+| Option                        | Description                                                            |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `--agent <name>`              | Coding agent for every session: `codex` or `claude` (default: `codex`) |
+| `--prompt-file <path>`        | Read the feature instructions from a file                              |
+| `--cwd <directory>`           | Workspace directory for every session (default: current directory)     |
+| `--max-iterations <count>`    | Maximum number of agent sessions to launch (default: 10)               |
+| `--session-timeout <seconds>` | Stop the run if a single session exceeds this many seconds             |
+| `--model <name>`              | Model for every session, passed to the agent unchanged                 |
+| `--reasoning-effort <level>`  | Reasoning effort for every session, passed to the agent unchanged      |
+
+Run `afk --help` for the exit codes.
+
+Progress is printed to stderr as `[afk]` lines. When a session fails to execute, the last 20 lines of the agent's stderr
+are printed after the `Execution error` line.
+
+## Supported agents
+
+Prerequisites are not checked up front: a missing executable is a launch failure and follows the normal retry-once
+policy. In every case the prompt is delivered on stdin and the workspace is the directory given by `--cwd`.
+
+### Codex (`--agent codex`)
+
+- **Prerequisites:** Codex CLI installed and authenticated, with `--approve-for-me` support.
+- **Launch:** `codex exec --approve-for-me -C <workspace> --output-last-message <file> [--model <model>] [--config model_reasoning_effort="<effort>"] -`.
+  The final message is the content of `<file>`, a temporary file outside the workspace that `afk` removes after the
+  session; Codex's stdout is a progress log and is ignored.
+- **Honored settings:** workspace, `--model`, `--reasoning-effort`.
+
+### Claude Code (`--agent claude`)
+
+- **Prerequisites:** Claude Code CLI installed and authenticated; `auto` permission mode available for the account and
+  model; the `code` skill discoverable by Claude Code (for example under `.claude/skills`).
+- **Launch:** `claude -p --output-format json --permission-mode auto [--model <model>] [--effort <effort>]`, run in the
+  workspace. The final message is the `result` field of the JSON object on stdout; `is_error: true` is an execution error.
+- **Honored settings:** workspace, `--model`, `--reasoning-effort` (passed as `--effort`).
+
+`afk` never selects a full-access mode for any agent.
+
+## Development
+
+```
+pnpm check   # test, typecheck, lint, prettier
+pnpm test    # build once, then run both test suites
+pnpm test:unit # run unit tests without building
+pnpm test:integration # build, then run CLI integration tests
+pnpm test:coverage # build, test, and generate coverage reports
+```
+
+See [Testing](doc/TESTING.md#coverage) for coverage reports in CI and their scope.
+
+## Publishing
+
+The [Publish to npm](.github/workflows/publish.yml) workflow runs only when started manually from `main`. It uses npm
+trusted publishing through GitHub Actions OIDC, so it needs no npm token secret. In the `@laskaridis/afk` package settings
+on npmjs.com, add a **GitHub Actions** trusted publisher with these values:
+
+| Setting              | Value         |
+| -------------------- | ------------- |
+| Organization or user | `laskaridis`  |
+| Repository           | `afk3`        |
+| Workflow filename    | `publish.yml` |
+
+Leave the optional environment name empty and enable **Allow npm publish**. Once the workflow is on `main` and the
+trusted publisher is configured, run it from the repository's **Actions** tab.
+
+The workflow runs `pnpm check` and publishes the version in `package.json`. Bump that version before each later release;
+npm will not accept a version that has already been published or unpublished. The package is currently set to `1.0.0`;
+`0.1.0` was previously unpublished. npm blocks republishing a fully unpublished package name for 24 hours. If the package
+Settings page is no longer available, first publish an unused version interactively after that hold, configure the
+trusted publisher, then bump the version again before running the workflow.

package/dist/agents/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/agents/agent-input.js

@@ -0,0 +1 @@
+export {};

package/dist/agents/claude.js

@@ -0,0 +1,38 @@
+/** Adapter for Claude Code, run in non-interactive print mode with JSON output. */
+export class ClaudeAdapter {
+    name = "claude";
+    executable = "claude";
+    /** Builds `claude -p` arguments with JSON output and `auto` permission mode, plus `--model` and `--effort` if given. */
+    buildArgs({ model, effort }) {
+        // The prompt arrives on stdin in print mode; the workspace is the process's working directory.
+        const args = ["-p", "--output-format", "json", "--permission-mode", "auto"];
+        if (model !== undefined)
+            args.push("--model", model);
+        if (effort !== undefined)
+            args.push("--effort", effort);
+        return args;
+    }
+    /**
+     * Reads the final message from the `result` field of the JSON document on stdout. Empty output or a blank result
+     * is `missing`, unparseable output is `invalid`, and `is_error: true` is an `agentError` carrying the `subtype`.
+     */
+    extractFinalMessage(stdout) {
+        if (stdout.trim() === "")
+            return { missing: true };
+        let parsed;
+        try {
+            parsed = JSON.parse(stdout);
+        }
+        catch {
+            return { invalid: true, reason: "agent output could not be parsed" };
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { invalid: true, reason: "agent output could not be parsed" };
+        }
+        const { is_error, subtype, result } = parsed;
+        if (is_error === true) {
+            return { agentError: true, detail: typeof subtype === "string" && subtype !== "" ? subtype : "unknown" };
+        }
+        return typeof result === "string" && result.trim() !== "" ? { message: result } : { missing: true };
+    }
+}

package/dist/agents/codex.js

@@ -0,0 +1,33 @@
+/** Adapter for Codex, run through `codex exec` with the final message written to a file. */
+export class CodexAdapter {
+    name = "codex";
+    executable = "codex";
+    /**
+     * Builds `codex exec` arguments: the working directory, `--output-last-message` when an output file is given,
+     * `--model` and the reasoning-effort config if given, and `-` so the prompt is read from stdin.
+     */
+    buildArgs({ cwd, outputFile, model, effort }) {
+        const args = ["exec", "--approve-for-me", "-C", cwd];
+        // Stdout is a progress log; the final message is only reliable in the output file.
+        if (outputFile !== undefined)
+            args.push("--output-last-message", outputFile);
+        if (model !== undefined)
+            args.push("--model", model);
+        if (effort !== undefined)
+            args.push("--config", `model_reasoning_effort=${JSON.stringify(effort)}`);
+        // `-` makes Codex read the prompt from stdin.
+        args.push("-");
+        return args;
+    }
+    /**
+     * Codex's stdout is a progress log (reasoning, tool calls), so it is ignored here. Instead `buildArgs` asks Codex
+     * to write its last message to a file via `--output-last-message`; the session reads that file after Codex exits
+     * and hands its content in as `outputFile`.
+     *
+     * The content is returned as-is. Finding the `<afk-harness-result>` block inside it is the workflow step's job.
+     * No file, or a blank one, means Codex never produced a final message.
+     */
+    extractFinalMessage(_stdout, outputFile) {
+        return outputFile === undefined || outputFile.trim() === "" ? { missing: true } : { message: outputFile };
+    }
+}

package/dist/agents/registry.js

@@ -0,0 +1,22 @@
+import { ClaudeAdapter } from "./claude.js";
+import { CodexAdapter } from "./codex.js";
+/** The single list of supported agents; register new adapters here. */
+export class AgentRegistry {
+    adapters;
+    /** @param adapters The supported agents; defaults to all built-in adapters. Names must be unique. */
+    constructor(adapters = [new CodexAdapter(), new ClaudeAdapter()]) {
+        this.adapters = new Map(adapters.map((adapter) => [adapter.name, adapter]));
+    }
+    /** The agent used when `--agent` is not given. */
+    get defaultName() {
+        return "codex";
+    }
+    /** Supported agent names in registration order. */
+    names() {
+        return [...this.adapters.keys()];
+    }
+    /** The adapter registered under `name`, or `undefined` if there is none. */
+    get(name) {
+        return this.adapters.get(name);
+    }
+}

package/dist/cli/cli-exit-codes.js

@@ -0,0 +1,41 @@
+/** Process exit codes of the CLI, by the outcome that produces them. */
+export const EXIT_CODES = {
+    complete: 0,
+    blocked: 1,
+    inputError: 2,
+    executionError: 3,
+    iterationLimit: 4,
+    timeout: 5,
+    interrupted: 130,
+};
+const EXIT_CODE_MEANINGS = {
+    complete: "the feature was reported complete",
+    blocked: "the code skill reported a blocker",
+    inputError: "invalid options or prompt input; no session was launched",
+    executionError: "the agent failed to execute twice in a row",
+    iterationLimit: "the iteration limit was reached without reported completion",
+    timeout: "a session exceeded --session-timeout",
+    interrupted: "interrupted by the user (Ctrl+C)",
+};
+/** The "Exit codes" section appended to `--help`, one line per code with its meaning. */
+export function formatExitCodeHelp() {
+    const lines = Object.keys(EXIT_CODES).map((name) => `  ${String(EXIT_CODES[name]).padEnd(4)}${EXIT_CODE_MEANINGS[name]}`);
+    return `\nExit codes:\n${lines.join("\n")}\n`;
+}
+/** Maps the terminal event of a run to the process exit code. */
+export function exitCodeFor(result) {
+    switch (result.type) {
+        case "WorkflowFinished":
+            return EXIT_CODES.complete;
+        case "WorkflowBlocked":
+            return EXIT_CODES.blocked;
+        case "WorkflowFailed":
+            return EXIT_CODES.executionError;
+        case "MaxIterationsReached":
+            return EXIT_CODES.iterationLimit;
+        case "WorkflowTimedOut":
+            return EXIT_CODES.timeout;
+        case "WorkflowInterrupted":
+            return EXIT_CODES.interrupted;
+    }
+}

package/dist/cli/cli-options.js

@@ -0,0 +1,91 @@
+import { statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { DEFAULT_MAX_ITERATIONS } from "../workflow/workflow-executor.js";
+import { EXIT_CODES, formatExitCodeHelp } from "./cli-exit-codes.js";
+const MAX_TIMER_MS = 2 ** 31 - 1;
+function parseMaxIterations(value) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new InvalidArgumentError("must be a positive integer.");
+    }
+    return Number(value);
+}
+function parseSessionTimeout(value) {
+    if (!/^\d+(\.\d+)?$/.test(value) || Number(value) <= 0) {
+        throw new InvalidArgumentError("must be a positive number of seconds.");
+    }
+    // setTimeout treats delays above 2^31-1 ms as 1 ms.
+    if (Number(value) * 1000 > MAX_TIMER_MS) {
+        throw new InvalidArgumentError(`must be at most ${Math.floor(MAX_TIMER_MS / 1000)} seconds.`);
+    }
+    return Number(value);
+}
+function parseNonEmpty(value) {
+    if (value.trim() === "")
+        throw new InvalidArgumentError("must not be empty.");
+    return value;
+}
+function parseCwd(value) {
+    const directory = resolve(value);
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(directory).isDirectory();
+    }
+    catch {
+        // reported below
+    }
+    if (!isDirectory)
+        throw new InvalidArgumentError(`${value} is not an existing directory.`);
+    return directory;
+}
+function readVersion() {
+    // Resolves to the repository's package.json from both src/cli/ and dist/cli/.
+    const require = createRequire(import.meta.url);
+    return require("../../package.json").version;
+}
+/**
+ * Parse and validate argv. Help wins over every other option.
+ *
+ * Help, version and invalid input are not thrown: they are returned as `{ kind: "exit" }` with code 0 for help and
+ * version and `EXIT_CODES.inputError` otherwise, after commander has printed its output.
+ *
+ * @param argv The full process argument vector, including the node and script entries.
+ * @param registry Supplies the valid `--agent` names and the default.
+ */
+export function parseOptions(argv, registry) {
+    const parseAgent = (value) => {
+        if (!registry.names().includes(value)) {
+            throw new InvalidArgumentError(`must be one of: ${registry.names().join(", ")}.`);
+        }
+        return value;
+    };
+    const program = new Command()
+        .name("afk")
+        .description("Leave the coding agent implementing a feature, one task at a time, while you are away from keyboard")
+        .version(readVersion())
+        .argument("[prompt...]", "feature instructions (or use --prompt-file, or pipe on stdin)")
+        .option("--agent <name>", `coding agent for every session (supported: ${registry.names().join(", ")}; default: ${registry.defaultName})`, parseAgent, registry.defaultName)
+        .option("--prompt-file <path>", "read the feature instructions from a file")
+        .option("--cwd <directory>", "workspace directory for every session (default: current directory)", parseCwd)
+        .option("--max-iterations <count>", "maximum number of agent sessions to launch", parseMaxIterations, DEFAULT_MAX_ITERATIONS)
+        .option("--session-timeout <seconds>", "stop the run if a single session exceeds this many seconds", parseSessionTimeout)
+        .option("--model <name>", "model for every session, passed to the agent unchanged (default: the agent's configuration)", parseNonEmpty)
+        .option("--reasoning-effort <level>", "reasoning effort for every session, passed to the agent unchanged (default: the agent's configuration)", parseNonEmpty)
+        .addHelpText("after", formatExitCodeHelp())
+        .exitOverride();
+    try {
+        const optionArgs = argv.slice(2);
+        const endOfOptions = optionArgs.indexOf("--");
+        const valueOptions = new Set(program.options.filter((o) => o.required || o.optional).map((o) => o.long));
+        const helpRequested = (endOfOptions === -1 ? optionArgs : optionArgs.slice(0, endOfOptions)).some((arg, i, args) => (arg === "--help" || arg === "-h") && !valueOptions.has(args[i - 1]));
+        program.parse(helpRequested ? [...argv.slice(0, 2), "--help"] : argv);
+    }
+    catch (error) {
+        if (error instanceof CommanderError)
+            return { kind: "exit", code: error.exitCode === 0 ? 0 : EXIT_CODES.inputError };
+        throw error;
+    }
+    const { cwd = process.cwd(), ...rest } = program.opts();
+    return { kind: "run", options: { ...rest, cwd, positional: program.args } };
+}

package/dist/cli/cli.js

@@ -0,0 +1,58 @@
+import { AgentRegistry } from "../agents/registry.js";
+import { ConsoleReporter } from "../reporting/console-reporter.js";
+import { SessionExecutorFactory } from "../session/session-executor-factory.js";
+import { WorkflowExecutor } from "../workflow/workflow-executor.js";
+import { EXIT_CODES, exitCodeFor } from "./cli-exit-codes.js";
+import { resolvePrompt } from "./launch-prompt.js";
+import { parseOptions } from "./cli-options.js";
+async function readAllStdin() {
+    process.stdin.setEncoding("utf8");
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+/** Parses options, resolves the launch prompt, wires and runs the workflow, and returns the process exit code. */
+export class CLI {
+    registry = new AgentRegistry();
+    /**
+     * Runs the CLI.
+     *
+     * @param argv The full process argument vector, including the node and script entries.
+     * @returns The exit code for the process; input problems are reported on stderr and returned, not thrown.
+     */
+    async run(argv) {
+        const parsed = parseOptions(argv, this.registry);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const { options } = parsed;
+        const resolved = await resolvePrompt({
+            positional: options.positional,
+            promptFile: options.promptFile,
+            stdinIsTTY: Boolean(process.stdin.isTTY),
+            readStdin: readAllStdin,
+        });
+        if (!resolved.ok) {
+            process.stderr.write(`[afk] input error: ${resolved.message}\n`);
+            return EXIT_CODES.inputError;
+        }
+        const interruption = new AbortController();
+        // Repeated signals are absorbed: the first one already stops the run.
+        for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+            process.on(signal, () => interruption.abort());
+        const graceMs = Number(process.env.AFK_TERMINATION_GRACE_MS) || undefined;
+        const sessionFactory = new SessionExecutorFactory(interruption.signal, options.sessionTimeout, graceMs);
+        const workflowOptions = {
+            adapter: this.registry.get(options.agent),
+            model: options.model,
+            effort: options.reasoningEffort,
+            maxIterations: options.maxIterations,
+            sessionTimeoutSeconds: options.sessionTimeout,
+            cwd: options.cwd,
+        };
+        const launchPrompt = { text: resolved.prompt };
+        const workflow = new WorkflowExecutor(workflowOptions, launchPrompt, sessionFactory);
+        workflow.subscribe(new ConsoleReporter(process.stderr));
+        return exitCodeFor(await workflow.run());
+    }
+}

package/dist/cli/launch-prompt.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+const isBlank = (text) => text.trim() === "";
+/**
+ * Resolve exactly one launch prompt; sources are never combined.
+ *
+ * Never throws for bad input: no source, several sources, an unreadable file or a blank prompt are returned as
+ * `{ ok: false, message }`.
+ */
+export async function resolvePrompt(input) {
+    if (input.positional.length > 1) {
+        return { ok: false, message: "expected a single prompt argument, got " + input.positional.length };
+    }
+    // Stdin is only a fallback: a TTY is never read, and an explicit source means a
+    // non-TTY stdin that is left open (cron, CI) must not block the run.
+    const explicit = input.positional.length === 1 || input.promptFile !== undefined;
+    const stdin = input.stdinIsTTY || explicit ? "" : await input.readStdin();
+    const sources = [];
+    if (input.positional.length === 1)
+        sources.push({ name: "positional argument", text: input.positional[0] });
+    if (input.promptFile !== undefined) {
+        try {
+            sources.push({ name: `prompt file ${input.promptFile}`, text: await readFile(input.promptFile, "utf8") });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { ok: false, message: `cannot read prompt file ${input.promptFile}: ${reason}` };
+        }
+    }
+    if (!isBlank(stdin))
+        sources.push({ name: "stdin", text: stdin });
+    if (sources.length === 0) {
+        return {
+            ok: false,
+            message: "no prompt provided: pass a prompt argument, --prompt-file <path>, or pipe it on stdin",
+        };
+    }
+    if (sources.length > 1) {
+        return {
+            ok: false,
+            message: `multiple prompt sources given (${sources.map((s) => s.name).join(", ")}); use exactly one`,
+        };
+    }
+    const [source] = sources;
+    if (isBlank(source.text))
+        return { ok: false, message: `the ${source.name} is empty` };
+    return { ok: true, prompt: source.text };
+}

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { CLI } from "./cli/cli.js";
+new CLI().run(process.argv).then((code) => process.exit(code), (error) => {
+    process.stderr.write(`[afk] ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(2);
+});

package/dist/code.md

@@ -0,0 +1,152 @@
+## Goal
+
+You are an autonomous coding agent stuck on a loop, writing code to implement the feature that has been assigned to you by the user.
+
+**Important:** While you are working on the task the user is AFK, so don't assume they are available to answer questions or provide clarifications.
+
+## User input
+
+The user MUST specify a list of tasks and a feature specification to you. If either is missing, STOP and return a `blocked` result with the missing input and exact unblock condition, as per the required coding protocol below.
+
+The user MAY also explicitly specify one task to work on by its exact task id (for example, `Work on TASK-011`). When provided, this assignment takes precedence over automatic task selection.
+
+## Workflow 
+
+### 1. Understand what needs to be done.
+
+Before you write a single line of code:
+- Read the user-provided spec file and task list to understand the broader context of the task.
+- Read the feature's implementation notes (if available) to understand what has been done so far.
+- Inspect the relevant codebase as needed to build understanding.
+- Make sure you read any documentation about ubiquitous domain language if present in the project.
+
+### 2. Select ONE task and implement it.
+
+- If the user explicitly specified a task, select only that task from the provided task list. Do not pick a different task or fall back to automatic selection. An explicit assignment may revisit a task already marked complete; inspect its current implementation and any supplied findings before making changes.
+  - If the specified task cannot be uniquely identified in the task list, STOP and return `blocked` with `task_id:null`, explaining the problem and requiring a valid, unambiguous task id.
+  - If the specified task has pending dependencies, STOP and return `blocked` with that task's exact id, identifying the dependencies that must be completed. Do not implement a dependency instead.
+- If the user did not explicitly specify a task, pick the **highest priority** task from the task list provided which is not implemented yet and doesn't have any pending dependencies.
+- Make sure you are working on a single task at a time.
+- Use the tdd skill (RED -> GREEN -> REFACTOR) to implement that single task. Check for any relevant skills available.
+- Follow the established ubiquitous domain language used in the project, don't invent your own.
+- Follow the established architecture, domain boundaries, and project conventions. Do not make material architectural or product-policy decisions that contradict or extend the specification.
+- Constrain your changes strictly to the scope of the task implemented. Do not introduce unrelated behavior, speculative abstractions, or unnecessary refactoring.
+- Assume you are working in the correct isolated project workspace for this feature. No need to create git branch or worktree.
+- Prefer minimal, cohesive changes that satisfy the task's acceptance criteria.
+- Keep notes of your progress using the progress report format shown below (create it if missing).
+
+### 3. Sign-off.
+
+- Don't assume your code passes that tests. Run all test with the broadest available test command to verify they all pass.
+- Mark the task as complete in the task list. Before marking a task completed, evaluate every acceptance criterion from the task definition. Record the evidence supporting each criterion. Passing tests alone are insufficient if they do not establish that the acceptance criteria have been satisfied.
+- Commit only files modified by the current task and explicitly authorized bookkeeping files. Never stage or commit unrelated or pre-existing changes.
+- Ensure you record the verification evidence and update the task status before committing them together with the implementation.
+- Respond with the appropriate response contract based on the stop condition, as explained below.
+
+For non-trivial changes, delegate a read-only review of the selected task’s implementation against its specification, acceptance criteria, and scope. Assess concrete findings and resolve completion blockers before marking the task complete.
+
+## Constraints
+
+- Validation tasks are read-only except for evidence/reporting files such as the task list provided by the user and `<feature-name-slug>.code.md`.
+- If validation finds an defect create a follow-up task instead of fixing the defect inside the validation task.
+- Every task marked completed must have a matching progress entry in `<feature-name-slug>.code.md` using the exact task id.
+- Record all modified files and relevant implementation decisions in the progress report.
+- Never commit unrelated or pre-existing changes.
+
+## Implementation notes file and progress report format
+
+Store implementation notes in `<feature-name-slug>.code.md` in the same folder as the user-provided specification. Derive the filename by replacing the specification's `.spec.md` suffix with `.code.md` (for example, `specs/001-afk-cli-core.spec.md` uses `specs/001-afk-cli-core.code.md`). If the specification does not end in `.spec.md`, replace its final extension with `.code.md`. Use this same notes file across iterations and create it if missing.
+
+You leave notes to yourself in `<feature-name-slug>.code.md` which you can revisit in successive iterations. For each iteration APPEND, NEVER replace, ALWAYS append to maintain traceability:
+
+```
+## [Timestamp]
+- Task id
+- What was implemented:
+  - ...
+- Files changed:
+  - ...
+- Verification:
+  Records concrete evidence on how you know the task is actually done, for example:
+  - commands run and their outcome
+  - checks performed
+  - observed runtime results
+  - artifacts prduced
+  - ...
+- Learnings for future iterations:
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+- Scope deviations:
+  -  Must explicitly list all unplanned files touched and why.
+- Follow up needed: If a validation or smoke-check task finds a defect, explicitly name the new fix task instead of silently folding the fix into the validation enty.
+---
+```
+
+Keeping all sections are important - they help future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate discoveries
+
+If you discover something that will be relevant for future iterations, add it to the `## Project discovery` section at the TOP of `<feature-name-slug>.code.md`. This section should consolidate the most important learnings:
+
+```
+## Project discovery 
+- Use `sql<number>` template for aggregations
+- Always use `IF NOT EXISTS` for migrations
+- Export types from actions.ts for UI components
+---
+```
+
+Only add discoveries that are **general and reusable**, not task-specific details.
+
+## Coding loop protocol
+
+Treat these instructions as a stable API between you and host coding harness. They are mandatory and need to follow them **to the letter**.
+
+### Response 
+
+Your final response to the user MUST end with exactly one result block, wrapped in the tags below and carrying this session's nonce, `{{NONCE}}`. The harness parses the last block with this exact nonce, so copy it exactly and do not place any other text after the block.
+
+```
+<afk-harness-result nonce="{{NONCE}}">
+{"outcome":"complete","task_id":"TASK-011","task_plan_file":"specs/feature.plan.json"}
+</afk-harness-result>
+```
+
+The block body MUST be exactly one JSON object and nothing else: do not wrap it in markdown fences or add prose inside the block.
+
+The JSON object MUST use one of these shapes:
+
+- `{"outcome":"repeat","task_id":"TASK-011","task_plan_file":"specs/feature.plan.json"}`
+- `{"outcome":"complete","task_id":"TASK-011","task_plan_file":"specs/feature.plan.json"}`
+- `{"outcome":"blocked","blocker_text":"...","task_id":"TASK-011","task_plan_file":"specs/feature.plan.json"}`
+- `{"outcome":"fail","failure_summary":"...","task_id":"TASK-011","task_plan_file":"specs/feature.plan.json"}`
+
+If no task could be selected, use `blocked` with `task_id:null`. For example, when no task plan file was specified:
+`{"outcome":"blocked","blocker_text":"Provide a task plan file so a task can be selected.","task_id":null,"task_plan_file":null}`
+
+Rules:
+
+- `outcome` must be one of `repeat`, `complete`, `blocked`, or `fail`.
+- Always include `task_id` and `task_plan_file` in the result block for every outcome.
+- `task_id` must be the exact identifier from the task list of the task selected for implementation during this iteration. Always retain this identifier even if the attempt was blocked or failed and the task was not implemented. Use `null` only when no task plan file was specified or no task could be selected; in either case, the outcome MUST be `blocked`. Do not substitute the identifier of a follow-up task for the task attempted.
+- `task_plan_file` must be the path to the actual task list plan file used during this iteration, relative to the project root when possible. Use `null` only when no task plan file was available. Do not substitute the specification or implementation notes file.
+- Each metadata value must be a non-empty string or JSON `null`, never an empty string or the string `"null"`.
+- `blocked` responses must include a non-empty `blocker_text` string.
+- `fail` responses must include a non-empty `failure_summary` string.
+- No fields other than `outcome`, `task_id`, `task_plan_file`, and the outcome's required `blocker_text` or `failure_summary` are allowed.
+- Leading and trailing whitespace around the JSON object inside the block is allowed, but any
+  other text inside the block is a contract violation.
+- A block with a different nonce, or no block at all, is a contract violation.
+
+### Stop condition
+
+After completing a task, check if ALL tasks have been completed:
+
+- If ALL tasks are complete and passing, use the `complete` outcome.
+- If there are still tasks incomplete, use the `repeat` outcome.
+- If progress is blocked by environment/runtime prerequisites after a revalidation pass (same blocker signature, no code-level next step), use the `blocked` outcome and provide the blocker reason plus exact unblock condition.
+- If the required specification or task list is missing, use the `blocked` outcome and identify what the user must provide.
+- If no task could be selected for implementation, use the `blocked` outcome with `task_id:null` and explain why selection was impossible and the exact unblock condition.
+- If a permission denial or material ambiguity leaves no authorized next step after checking the available context, use the `blocked` outcome and provide the reason plus exact unblock condition. Continue with an authorized alternative when one exists.
+- If validation finds a defect, use the `fail` outcome and generate a follow-up fix task instead of silently folding the fix into the validation entry.

package/dist/reporting/console-reporter.js

@@ -0,0 +1,46 @@
+/** Writes today's `[afk]` status lines for workflow events to its sink. WorkflowFailed has no final line. */
+export class ConsoleReporter {
+    sink;
+    /** @param sink Where the status lines are written. */
+    constructor(sink) {
+        this.sink = sink;
+    }
+    /** Writes the status line for `event`, if it has one; other events are ignored. */
+    onEvent(event) {
+        switch (event.type) {
+            case "IterationStarted":
+                if (!event.retry)
+                    this.line(`Iteration ${event.iteration}/${event.limit}: starting agent session`);
+                break;
+            case "StepExecutionRetried":
+                this.line(`Iteration ${event.iteration}/${event.limit}: retrying agent session after execution error`);
+                break;
+            case "StepExecutionFailed":
+                this.line(`Task failure: ${event.failureSummary}`);
+                break;
+            case "SessionExecutionErrorOccurred":
+                this.line(`Execution error: ${event.detail}`, event.stderrTail);
+                break;
+            case "WorkflowFinished":
+                this.line("Run complete: feature complete");
+                break;
+            case "WorkflowBlocked":
+                this.line(`Run blocked: ${event.blockerText}`);
+                break;
+            case "MaxIterationsReached":
+                this.line(`Run stopped: iteration limit of ${event.limit} reached without reported completion`);
+                break;
+            case "WorkflowTimedOut":
+                this.line(`Run stopped: agent session timed out after ${event.seconds} seconds`);
+                break;
+            case "WorkflowInterrupted":
+                this.line("Run interrupted by user");
+                break;
+            default:
+                break;
+        }
+    }
+    line(message, extra = []) {
+        this.sink.write([`[afk] ${message}`, ...extra].map((text) => `${text}\n`).join(""));
+    }
+}

package/dist/reporting/reporter-output-sink.js

@@ -0,0 +1 @@
+export {};

package/dist/reporting/reporter.js

@@ -0,0 +1 @@
+export {};

package/dist/session/session-executor-factory.js

@@ -0,0 +1,21 @@
+import { SessionExecutor } from "./session-executor.js";
+/** Holds the run-wide session settings so every session gets the same signal, timeout and grace period. */
+export class SessionExecutorFactory {
+    signal;
+    timeoutSeconds;
+    graceMs;
+    /**
+     * @param signal Aborting it interrupts the running session and ends later ones as interrupted.
+     * @param timeoutSeconds Per-session timeout; no timeout when omitted.
+     * @param graceMs Wait between termination escalation steps; the executor's default when omitted.
+     */
+    constructor(signal, timeoutSeconds, graceMs) {
+        this.signal = signal;
+        this.timeoutSeconds = timeoutSeconds;
+        this.graceMs = graceMs;
+    }
+    /** Creates a new `SessionExecutor` for `adapter` with the run-wide settings. */
+    create(adapter) {
+        return new SessionExecutor(adapter, this.signal, this.timeoutSeconds, this.graceMs);
+    }
+}

package/dist/session/session-executor.js

@@ -0,0 +1,160 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Default wait between termination escalation steps (SIGINT, SIGTERM, SIGKILL). */
+export const DEFAULT_TERMINATION_GRACE_MS = 5000;
+/** How many trailing stderr lines are kept for reporting a failed session. */
+export const STDERR_TAIL_LINES = 20;
+/** Runs exactly one non-interactive agent process and classifies how the session ended. */
+export class SessionExecutor {
+    adapter;
+    signal;
+    timeoutSeconds;
+    graceMs;
+    constructor(adapter, 
+    /** Aborting interrupts the child and ends the session as `interrupted` once it has exited. */
+    signal, 
+    /** Interrupts and terminates the child once this many seconds have elapsed. */
+    timeoutSeconds, 
+    /** Wait between escalation steps (SIGINT, then SIGTERM, then SIGKILL). */
+    graceMs = DEFAULT_TERMINATION_GRACE_MS) {
+        this.adapter = adapter;
+        this.signal = signal;
+        this.timeoutSeconds = timeoutSeconds;
+        this.graceMs = graceMs;
+    }
+    /**
+     * Runs one agent process to the end and classifies how it ended.
+     *
+     * Resolves with a `SessionResult` for every outcome, including launch failure, timeout and interruption; it is not
+     * expected to reject. If the signal is already aborted no process is started.
+     */
+    async execute(input) {
+        if (this.signal.aborted)
+            return { kind: "interrupted" };
+        const outputDir = await mkdtemp(join(tmpdir(), "afk-session-"));
+        try {
+            return await this.run(input, join(outputDir, "final-message.txt"));
+        }
+        finally {
+            await rm(outputDir, { recursive: true, force: true });
+        }
+    }
+    async run(input, outputPath) {
+        const args = this.adapter.buildArgs({
+            cwd: input.cwd,
+            outputFile: outputPath,
+            model: input.model,
+            effort: input.effort,
+        });
+        let interrupted = false;
+        let timedOut = false;
+        const outcome = await new Promise((resolve) => {
+            const child = spawn(this.adapter.executable, args, { cwd: input.cwd, stdio: ["pipe", "pipe", "pipe"] });
+            const cleanups = [];
+            const settle = (result) => {
+                cleanups.forEach((cleanup) => cleanup());
+                resolve(result);
+            };
+            let stdout = "";
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => (stdout += chunk));
+            const stderr = new TailBuffer(STDERR_TAIL_LINES);
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", (chunk) => stderr.write(chunk));
+            // The agent may exit before reading its prompt; that surfaces through its exit status.
+            child.stdin.on("error", () => { });
+            child.stdin.end(input.prompt);
+            child.once("error", (error) => settle({ error }));
+            child.once("close", (exitCode, exitSignal) => settle({ exitCode, signal: exitSignal, stdout, stderrTail: stderr.lines() }));
+            // Forward the interruption, then escalate until the child is gone. Never detached.
+            const escalation = [];
+            const interrupt = () => {
+                if (interrupted)
+                    return;
+                interrupted = true;
+                // A timeout already started the escalation; the user's interrupt just takes over the reason.
+                if (!timedOut)
+                    terminate();
+            };
+            const terminate = () => {
+                child.kill("SIGINT");
+                escalation.push(setTimeout(() => child.kill("SIGTERM"), this.graceMs));
+                escalation.push(setTimeout(() => child.kill("SIGKILL"), this.graceMs * 2));
+            };
+            if (this.timeoutSeconds !== undefined) {
+                const timer = setTimeout(() => {
+                    if (interrupted)
+                        return;
+                    timedOut = true;
+                    terminate();
+                }, this.timeoutSeconds * 1000);
+                cleanups.push(() => clearTimeout(timer));
+            }
+            if (this.signal.aborted)
+                interrupt();
+            else
+                this.signal.addEventListener("abort", interrupt, { once: true });
+            cleanups.push(() => {
+                this.signal.removeEventListener("abort", interrupt);
+                escalation.forEach(clearTimeout);
+            });
+        });
+        if ("error" in outcome)
+            return { kind: "launch-failed", detail: `failed to launch agent: ${outcome.error.message}` };
+        if (interrupted)
+            return { kind: "interrupted" };
+        if (timedOut)
+            return { kind: "timed-out" };
+        const outputFile = await readFile(outputPath, "utf8").catch(() => undefined);
+        return this.classify(outcome, outputFile);
+    }
+    /** Signal, then agent-reported error, then non-zero exit, then invalid, then missing. */
+    classify(exited, outputFile) {
+        const { exitCode, signal, stderrTail } = exited;
+        const failed = (detail) => ({ kind: "exited-unsuccessfully", detail, stderrTail });
+        if (signal)
+            return failed(`agent exited unsuccessfully with signal ${signal}`);
+        const extracted = this.adapter.extractFinalMessage(exited.stdout, outputFile);
+        if ("agentError" in extracted) {
+            return failed(exitCode === 0
+                ? `agent exited unsuccessfully (agent reported an error: ${extracted.detail})`
+                : `agent exited unsuccessfully with exit code ${exitCode} (agent reported an error: ${extracted.detail})`);
+        }
+        // A message from a failed process is never trusted.
+        if (exitCode !== 0)
+            return failed(`agent exited unsuccessfully with exit code ${exitCode}`);
+        if ("invalid" in extracted) {
+            return {
+                kind: "invalid-final-message",
+                detail: `agent final response is invalid: ${extracted.reason}`,
+                stderrTail,
+            };
+        }
+        if ("missing" in extracted) {
+            return { kind: "missing-final-message", detail: "agent exited without a final response", stderrTail };
+        }
+        return { kind: "success", finalMessage: extracted.message, stderrTail };
+    }
+}
+/** Keeps the last `max` lines of a text stream, including an unterminated final line. */
+class TailBuffer {
+    max;
+    completed = [];
+    partial = "";
+    constructor(max) {
+        this.max = max;
+    }
+    write(chunk) {
+        const parts = (this.partial + chunk).split("\n");
+        this.partial = parts.pop() ?? "";
+        this.completed.push(...parts);
+        if (this.completed.length > this.max)
+            this.completed = this.completed.slice(-this.max);
+    }
+    lines() {
+        const all = this.partial === "" ? this.completed : [...this.completed, this.partial];
+        return all.slice(-this.max);
+    }
+}

package/dist/session/session-input.js

@@ -0,0 +1 @@
+export {};

package/dist/session/session-result.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/coding-step.js

@@ -0,0 +1,71 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { parseResultBlock } from "./result-block.js";
+// Copied next to the compiled `workflow/` folder by the build script.
+const HARNESS = readFileSync(new URL("../code.md", import.meta.url), "utf8");
+const NONCE_PLACEHOLDER = "{{NONCE}}";
+function buildSessionPrompt(launchPrompt, nonce) {
+    return `${launchPrompt}\n\n---\n${HARNESS.replaceAll(NONCE_PLACEHOLDER, nonce)}\n`;
+}
+function toStepResult(block) {
+    const metadata = {};
+    if (block.task_id !== undefined)
+        metadata.task_id = block.task_id;
+    if (block.task_plan_file !== undefined)
+        metadata.task_plan_file = block.task_plan_file;
+    switch (block.outcome) {
+        case "repeat":
+            return { type: "Continue", ...metadata };
+        case "complete":
+            return { type: "Finished", ...metadata };
+        case "fail":
+            return { type: "StepFailed", failureSummary: block.failure_summary, ...metadata };
+        case "blocked":
+            return { type: "Blocked", blockerText: block.blocker_text, ...metadata };
+    }
+}
+/** One coding session: fresh nonce, session prompt, run, and the agent's result block as a step result. */
+export class CodingStep {
+    sessions;
+    name = "coding";
+    /** @param sessions Runs the agent process for this step. */
+    constructor(sessions) {
+        this.sessions = sessions;
+    }
+    /**
+     * Appends the harness instructions to `launchPrompt`, runs one session and reads the agent's result block.
+     * Session problems and contract violations come back as `SessionFailed`, not as exceptions.
+     */
+    async execute(launchPrompt, options) {
+        const nonce = randomBytes(4).toString("hex");
+        const session = await this.sessions.execute({
+            prompt: buildSessionPrompt(launchPrompt, nonce),
+            cwd: options.cwd,
+            model: options.model,
+            effort: options.effort,
+        });
+        switch (session.kind) {
+            case "interrupted":
+                return { type: "Interrupted" };
+            case "timed-out":
+                return { type: "Timeout" };
+            case "launch-failed":
+                return { type: "SessionFailed", detail: session.detail, stderrTail: [] };
+            case "exited-unsuccessfully":
+            case "missing-final-message":
+            case "invalid-final-message":
+                return { type: "SessionFailed", detail: session.detail, stderrTail: session.stderrTail };
+            case "success": {
+                const block = parseResultBlock(session.finalMessage, nonce);
+                if ("violation" in block) {
+                    return {
+                        type: "SessionFailed",
+                        detail: `agent final response is invalid: ${block.violation}`,
+                        stderrTail: session.stderrTail,
+                    };
+                }
+                return toStepResult(block);
+            }
+        }
+    }
+}

package/dist/workflow/launch-prompt.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/result-block.js

@@ -0,0 +1,87 @@
+/** The body of the last complete result block carrying this session's nonce, so echoed examples and noise are ignored. */
+function extractResultBody(text, nonce) {
+    const open = `<afk-harness-result nonce="${nonce}">`;
+    const close = "</afk-harness-result>";
+    let body;
+    for (let start = text.indexOf(open); start !== -1; start = text.indexOf(open, start + open.length)) {
+        const end = text.indexOf(close, start + open.length);
+        if (end === -1)
+            break;
+        body = text.slice(start + open.length, end);
+    }
+    return body;
+}
+const TEXT_FIELD_BY_OUTCOME = {
+    blocked: "blocker_text",
+    fail: "failure_summary",
+};
+/**
+ * Finds and validates the result block in an agent's final message.
+ *
+ * Only the last complete block carrying `nonce` counts. Never throws: a missing message, a missing block, malformed
+ * JSON or a field that breaks the contract is returned as a `ContractViolation`.
+ *
+ * @param text The agent's final message, if it produced one.
+ * @param nonce The session nonce the block must carry.
+ */
+export function parseResultBlock(text, nonce) {
+    if (text === undefined || text.trim() === "") {
+        return { violation: "the final message is missing or empty" };
+    }
+    const body = extractResultBody(text, nonce);
+    if (body === undefined) {
+        return { violation: `the final message has no <afk-harness-result nonce="${nonce}"> block` };
+    }
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        return {
+            violation: "the result block body is not a single JSON object (found prose, Markdown fences, or malformed JSON)",
+        };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { violation: "the result block is valid JSON but not a JSON object" };
+    }
+    const fields = value;
+    const metadata = {};
+    for (const key of ["task_id", "task_plan_file"]) {
+        if (!Object.hasOwn(fields, key))
+            continue;
+        const detail = fields[key];
+        if (detail !== null && (typeof detail !== "string" || detail.trim() === "")) {
+            return { violation: `"${key}" must be a non-empty string or null` };
+        }
+        metadata[key] = detail;
+    }
+    const outcomeKeys = Object.keys(fields).filter((key) => key !== "task_id" && key !== "task_plan_file");
+    const outcome = fields.outcome;
+    if (metadata.task_id === null && outcome !== "blocked") {
+        return { violation: 'a null "task_id" requires outcome "blocked" because no task could be selected' };
+    }
+    if (outcome === "repeat" || outcome === "complete") {
+        const extra = outcomeKeys.filter((key) => key !== "outcome");
+        if (extra.length > 0) {
+            return { violation: `outcome "${outcome}" must have no additional fields, found: ${extra.join(", ")}` };
+        }
+        return { outcome, ...metadata };
+    }
+    if (outcome === "blocked" || outcome === "fail") {
+        const field = TEXT_FIELD_BY_OUTCOME[outcome];
+        const extra = outcomeKeys.filter((key) => key !== "outcome" && key !== field);
+        if (extra.length > 0) {
+            return { violation: `outcome "${outcome}" has unsupported fields: ${extra.join(", ")}` };
+        }
+        const detail = fields[field];
+        if (typeof detail !== "string" || detail.trim() === "") {
+            return { violation: `outcome "${outcome}" requires a non-empty string "${field}"` };
+        }
+        return outcome === "blocked"
+            ? { outcome, blocker_text: detail, ...metadata }
+            : { outcome, failure_summary: detail, ...metadata };
+    }
+    return {
+        violation: `missing or unsupported "outcome" (expected repeat, complete, blocked, or fail)`,
+    };
+}

package/dist/workflow/workflow-event.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/workflow-executor.js

@@ -0,0 +1,127 @@
+import { CodingStep } from "./coding-step.js";
+/** Iteration limit used when the user does not set one. */
+export const DEFAULT_MAX_ITERATIONS = 10;
+/** An immutable copy of just the task fields of a step result, safe to embed in published events. */
+function taskOf(result) {
+    return Object.freeze({ task_id: result.task_id, task_plan_file: result.task_plan_file });
+}
+/**
+ * Runs the workflow loop and owns its policy.
+ *
+ * Each iteration runs one fresh `CodingStep` in a new session and interprets its result:
+ *
+ * - `Continue` and `StepFailed` end the iteration and the loop moves on to the next one.
+ * - `Finished`, `Blocked`, `Timeout` and `Interrupted` end the run immediately.
+ * - `SessionFailed` is retried once: a second consecutive failure ends the run, and any other result resets the
+ *   allowance. Retries count toward the iteration limit.
+ * - Reaching `maxIterations` without a terminal outcome ends the run as `MaxIterationsReached`.
+ *
+ * Everything that happens is published as a frozen `WorkflowEvent` to the subscribed observers, and the run resolves
+ * with the single terminal event. The executor reports nothing itself: output is up to the observers.
+ */
+export class WorkflowExecutor {
+    options;
+    launchPrompt;
+    sessions;
+    observers = [];
+    /**
+     * @param options Run configuration: the agent adapter, the iteration limit, and the working directory, model, effort
+     *   and session timeout passed to each step.
+     * @param launchPrompt The user's prompt, given to every step.
+     * @param sessions Creates the session executor for each iteration's step.
+     */
+    constructor(options, launchPrompt, sessions) {
+        this.options = options;
+        this.launchPrompt = launchPrompt;
+        this.sessions = sessions;
+    }
+    /** Registers an observer for all later events. Observers are notified in subscription order. */
+    subscribe(observer) {
+        this.observers.push(observer);
+    }
+    /**
+     * Runs iterations until a terminal outcome and returns the terminal event, which is also the last event published.
+     * Subscribe observers first: events published before they subscribe are not replayed.
+     */
+    async run() {
+        const { maxIterations } = this.options;
+        this.publish({ type: "WorkflowStarted", maxIterations });
+        let previousError;
+        for (let iteration = 1; iteration <= maxIterations; iteration++) {
+            const retry = previousError !== undefined;
+            this.publish({ type: "IterationStarted", iteration, limit: maxIterations, retry });
+            if (previousError !== undefined) {
+                this.publish({ type: "StepExecutionRetried", iteration, limit: maxIterations, previousError });
+            }
+            const step = new CodingStep(this.sessions.create(this.options.adapter));
+            this.publish({ type: "StepExecutionStarted", iteration, stepName: step.name });
+            const result = await step.execute(this.launchPrompt.text, {
+                cwd: this.options.cwd,
+                model: this.options.model,
+                effort: this.options.effort,
+            });
+            // Set when this iteration ends the run. IterationFinished is published first, then the terminal event.
+            let terminal;
+            switch (result.type) {
+                case "Continue":
+                    this.publish({ type: "StepExecutionFinished", iteration, task: taskOf(result) });
+                    break;
+                case "Finished":
+                    this.publish({ type: "StepExecutionFinished", iteration, task: taskOf(result) });
+                    terminal = { type: "WorkflowFinished", task: taskOf(result) };
+                    break;
+                case "StepFailed":
+                    this.publish({
+                        type: "StepExecutionFailed",
+                        iteration,
+                        failureSummary: result.failureSummary,
+                        task: taskOf(result),
+                    });
+                    break;
+                case "Blocked":
+                    this.publish({
+                        type: "StepExecutionBlocked",
+                        iteration,
+                        blockerText: result.blockerText,
+                        task: taskOf(result),
+                    });
+                    terminal = { type: "WorkflowBlocked", blockerText: result.blockerText, task: taskOf(result) };
+                    break;
+                case "SessionFailed":
+                    this.publish({
+                        type: "SessionExecutionErrorOccurred",
+                        iteration,
+                        detail: result.detail,
+                        stderrTail: result.stderrTail,
+                    });
+                    // One retry per consecutive error; a second consecutive error stops the run.
+                    if (previousError !== undefined) {
+                        terminal = { type: "WorkflowFailed", detail: result.detail, stderrTail: result.stderrTail };
+                    }
+                    else if (iteration === maxIterations) {
+                        terminal = { type: "MaxIterationsReached", limit: maxIterations };
+                    }
+                    break;
+                case "Timeout":
+                    terminal = { type: "WorkflowTimedOut", seconds: this.options.sessionTimeoutSeconds ?? 0 };
+                    break;
+                case "Interrupted":
+                    terminal = { type: "WorkflowInterrupted" };
+                    break;
+            }
+            this.publish({ type: "IterationFinished", iteration, outcome: result.type });
+            if (terminal !== undefined)
+                return this.publish(terminal);
+            // Only a session failure carries over: it makes the next iteration a retry.
+            previousError = result.type === "SessionFailed" ? result.detail : undefined;
+        }
+        return this.publish({ type: "MaxIterationsReached", limit: maxIterations });
+    }
+    /** Freezes the event, delivers it to every observer in order, and returns it so callers can return terminal events. */
+    publish(event) {
+        const frozen = Object.freeze(event);
+        for (const observer of this.observers)
+            observer.onEvent(frozen);
+        return frozen;
+    }
+}

package/dist/workflow/workflow-observer.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/workflow-options.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/workflow-step-options.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/workflow-step-result.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/workflow-step.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@laskaridis/afk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Leave a coding agent implementing a feature, one task at a time, while you are away from keyboard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laskaridis/afk3.git"
+  },
+  "bugs": "https://github.com/laskaridis/afk3/issues",
+  "homepage": "https://github.com/laskaridis/afk3#readme",
+  "type": "module",
+  "packageManager": "pnpm@9.15.1",
+  "bin": {
+    "afk": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"const fs=require('fs');fs.copyFileSync('src/code.md','dist/code.md');fs.chmodSync('dist/cli.js',0o755)\"",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "pnpm test && pnpm typecheck && pnpm lint && pnpm format:check && pnpm depcheck",
+    "test": "pnpm run build && vitest run",
+    "test:coverage": "pnpm run build && vitest run --coverage",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "pnpm run build && vitest run test/integration",
+    "depcheck": "depcruise src --config .dependency-cruiser.cjs"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-v8": "5.0.5",
+    "dependency-cruiser": "^18.7.2",
+    "eslint": "^10.13.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "^5.0.5"
+  }
+}