@dumbmice/pi-todo-loop 0.0.0-stage → 0.1.0

package/docs/behaviour.md

@@ -0,0 +1,162 @@
+# How it behaves, precisely
+
+The mechanics behind [README](../README.md). Read this when you are debugging behaviour, deciding
+whether to change a default, or wondering why the loop did something. It assumes you know that a
+**settle** is a model response with no tool calls — the only turn that can end a run.
+
+## The turn it adds
+
+`rpiv-todo` renders and stores the list but never asks pi for another turn. Pi ends a run when the model
+answers with no tool calls. This extension hooks that boundary: while the branch has open tasks it
+requests one more turn, so the model continues instead of handing control back.
+
+Two consequences follow from that being the only mechanism available:
+
+- **A continuation is a persisted entry.** pi has no "resume without appending anything", so each
+  continuation writes one `custom_message` with `display: false` and a constant body that states the
+  instruction (`Continue with the open todo tasks…`). It is invisible in the TUI, but it is in the
+  session file and, when no block is injected, it is what the model reads.
+- **Only a settle spends a round.** `turn_end` fires after every assistant response, including one that
+  ended in a tool call; those already cause pi's next request, so they cost nothing and write no marker.
+  A round, a strike and a marker therefore always concern a turn that would otherwise have ended the run.
+
+## Markers and role alternation
+
+A marker sits between two assistant turns, which is what keeps the conversation alternating: a request
+that contained `assistant → assistant` in a row is rejected by alternation-requiring providers.
+
+The `context` hook therefore keeps a marker only where it separates two assistant turns, and drops it
+when either neighbour is user-role: at the tail, immediately before your own message, or in a run of
+markers. The block replaces a marker tail, merges into a `user`/`custom` tail, and is appended after an
+assistant or toolResult tail.
+
+One exception is documented: `bashExecution`, `branchSummary` and `compactionSummary` tails cannot take
+a merge — pi rebuilds those from their own fields and ignores `content` — so the block becomes a
+separate message there and the request briefly holds two user-role messages. Losing the list on a
+compaction summary would be worse.
+
+## The injected block
+
+While tasks are open, every request ends with an ephemeral `<todo_loop_state>` block: the open tasks with
+their ids and statuses, and an instruction that yields to you. It is never persisted, which is why
+compaction cannot remove it.
+
+- **The block is user-role text and the last thing in the request.** It sits after your newest message
+  and says that your latest instruction outranks it. Models vary in how readily they take that
+  concession: one that reads your "stop" as authoritative will refuse, and those refusals cost up to
+  `maxRounds` turns. That is the same reason `injectState: false` exists.
+- **Task text is sanitised, not interpolated.** Subject, `activeForm` and `status` are model-authored —
+  possibly from a fetched page or a repo file — so every Unicode line terminator flattens, `<` is
+  escaped, controls/bidi/zero-width characters and unpaired surrogates are dropped, and labels truncate
+  by code point. Without this, a task subject could close the tag and forge a directive.
+- **The ids are the todo tool's own**, except where the stored list supplies an unusable or duplicate
+  id: that row moves to a free number so each row can be addressed, which means a `todo` call using the
+  shown number can fail when the tool wrote the list that way.
+- **A list cleared by `todo` calls alone is announced.** If every task goes from open to closed in a
+  turn whose only tool results were `todo`, a warning says so once. The loop's success state and its
+  failure state are the same observable.
+
+## Counters
+
+| Counter | Meaning | Reset by |
+|---|---|---|
+| `rounds` | continuations spent for the current human message | a new human message, `/todoloop reset`, a new process |
+| `strikes` | settles in a row that left the list unchanged | the list changing, a completed tool turn, a new human message |
+| `staleSettles` | settles since the list last changed | the list changing, a new human message |
+
+- **One budget per human message.** A user-role message carrying a `customType` (this extension's
+  marker, another extension's hidden message) is skipped when choosing the anchor, so it does not reset
+  the budget; `/todoloop` prints the anchor it is using.
+- **A stop keeps the budget shut.** Hitting the cap or the strike limit does not clear the counters, so
+  another extension's continuation or a provider retry under the same message cannot re-arm 12 rounds.
+  A queued human message is a new anchor and resets the budget the ordinary way.
+- **A stale list stops on the cap, not on strikes**, because any tool turn clears the strike budget.
+  That is why the cap reason appends `, list unchanged for N settles` — so a stale burn does not read
+  like healthy work.
+- **Errors do not close the budget.** A turn that ends `error` or `aborted` stops the loop for that turn
+  and spends no round; the counters are left as they are, so the next settle under the same message can
+  continue — which is what a provider retry hits.
+- **A stop is announced** once, when the reason changes, so a run cannot end silently on a cap.
+- **Counters live in memory.** `/reload`, a restart or a resumed session starts a new budget and
+  re-reads the list; a pause does not survive either.
+
+### Reason strings
+
+`/todoloop` prints one of these as `last:`. They are also announced when they change.
+
+| `last:` | Meaning |
+|---|---|
+| `continuing: round 1/12, 2 open` | working as intended |
+| `stopped: list is clear` | every remaining task is `completed`; a list whose tasks are all `deleted` reports `no list` instead |
+| `stopped: no list` | no recognised todo state on the branch — see the four causes below |
+| `stopped: 2 consecutive turns with no progress, 2 open` | the last two settles ran no tool and left the list unchanged |
+| `stopped: round cap 12 reached, 2 open` | the budget is spent; with `, list unchanged for N settles` appended, the model worked without updating the list |
+| `stopped: turn outcome was error` / `aborted` | the provider failed, or you aborted the turn |
+| `paused by user` | `/todoloop pause`; `/todoloop resume` or restart |
+| `resumed by user` | `/todoloop resume`; the next settle may continue |
+| `counters reset` | `/todoloop reset` cleared the rounds, strikes and list signature |
+| `idle` | nothing has run yet in this process |
+
+## Where the list comes from
+
+The list is read from the session branch on every request, never cached: a `rpiv-todo-state` custom
+entry's `data.tasks`, or a `todo` toolResult's `details.tasks`, whichever is newer.
+
+That is deliberate. A cache would owe invalidation on session switch, branch, compaction, process start
+and fork; and a resumed session with an open list would report `no list` until the model happened to
+call `todo` — the failure this package exists to prevent. The cost is one backward walk of the branch,
+sub-millisecond on thousands of entries.
+
+Two deviations follow from it:
+
+- **The branch is not the model's context.** After a compaction the model's context drops older
+  entries, but the reader still walks the whole branch, so `/todoloop` can report open work the model
+  has no list for. The panel and the model can disagree.
+- **A newer malformed entry is skipped** in favour of an older valid one, so after a shape change the
+  reader serves the list as of that change. Reading an errored `todo` call as "list clear" would be
+  worse.
+
+`no list` therefore has four causes: no todo tool installed, a tool that is not named `todo`, a shape
+this extension does not recognise, or every task `deleted`.
+
+## Scope
+
+- **A delegated child session runs its own loop.** Each session has its own list and counters, so a
+  subagent that loads this extension can continue independently of its parent; markers do not
+  interleave, but the work can.
+- **`/todoloop` needs an interactive session.** In `pi -p` and `--mode json` the loop runs, but there is
+  no UI for the status or the stop notification; the only signal is the marker count in the session
+  file and the model's final message.
+- **`.pi/todo-loop-off` stops every session started in that directory**; `~/.pi/agent/todo-loop-off`
+  stops all projects; the config file is global and re-read on every request, so editing it affects
+  running sessions.
+- **Nothing is written to your working tree.** The reads are the config, the two kill-switch paths and
+  the session branch.
+
+## Configuration limits
+
+Invalid config never fails a turn: missing, unreadable or invalid values fall back to the defaults.
+That includes values below `1` — `"maxRounds": 0` means "use 12", not "never continue". Numbers are
+clamped so a typo cannot defeat the cap it configures: `maxRounds` ≤ 1000, `maxStrikes` ≤ 100,
+`maxInjectedTasks` ≤ 50.
+
+## Cost
+
+- A continuation is a normal model turn: the whole conversation is sent again, so cost scales with the
+  number of continuations × session size. `maxRounds` caps continuations, not turns — tool turns are
+  pi's own and unbounded, so a long tool-heavy stretch can be many turns for one round. That, not the
+  block, is the dominant term.
+- `context` reads the config and probes the kill switch, and walks the branch only when it is going to
+  inject. `turn_end` does all three on every turn. While tasks are open the block adds ~100 tokens at
+  the tail; `injectState: false` adds none and leaves the model to call the todo tool's `list` action.
+- One small measurement on `deepseek-flash` (a 2.7k-token session, five turns): ~1,050 uncached input
+  tokens per turn with injection on against ~405 with `injectState: false`, and cache reads occurred in
+  both runs (16.0k vs 36.1k total). The block does not disable the prompt cache, but it and the head
+  rebuild cost a few hundred uncached tokens per request. An order of magnitude, not a benchmark — the
+  two runs took different trajectories.
+
+## More
+
+- [pi extension API alignment](pi-api-alignment.md) — the deliberate workarounds, with the pi version
+  each was verified against.
+- [AGENTS.md](../AGENTS.md) — layout, invariants, tests, release process.

package/docs/pi-api-alignment.md

@@ -0,0 +1,134 @@
+# pi extension API alignment
+
+How this extension's use of pi's extension API relates to the documented contract, and which exact
+versions that was established against.
+
+| Component | Tested version | Recorded in |
+|---|---|---|
+| `@earendil-works/pi-coding-agent` | **1.5.0** | `PI_API_SNAPSHOT` in `src/index.ts` |
+| `@juicesharp/rpiv-todo` | **2.15.0** | this file (item 12) |
+| Node | 22.23.2 | README *Tested against* |
+
+Last verified **2026-11-04**. Bump a row here, its constant where one exists, and the README table in
+the same commit as the change that depends on it.
+
+The contract is followed where it is documented: `turn_end` boundary proposals, draft entry types,
+`context` hook ownership of the message list, `display: false`, and `registerCommand`. Nothing here
+calls pi internals; item 1 nonetheless depends on behaviour pi documents nowhere, which is why it is
+listed below rather than assumed.
+
+What is unusual is not the API use but the *shape* of it: this extension exists to perform a
+continuation that pi does not expose as a single operation. Each client-side workaround is listed in
+full. Items that produce no signal in the transcript are marked _(silent)_.
+
+1. **One hidden entry per continuation, and only on a settle.** `turn_end` fires for every assistant
+   response, including one that ended in a tool call; such a turn already causes pi's next request, so
+   the hook returns early and spends nothing. `continue: true` is proposed only when the run would
+   otherwise end, and the proposed
+   projection must end on a message whose role is not `assistant` — otherwise the boundary reports an
+   invalid continuation and drops it. pi offers no `resume()` that appends nothing, so a continuation
+   is always expressed as *one* appended entry. We append a `custom_message` with `display: false`:
+   invisible in the TUI, about 200 bytes per continuation in the journal _(silent in the transcript)_.
+2. **Markers stay in history and are not stripped.** They sit between two assistant turns, so they are
+   what keeps the conversation alternating: `assistant → marker(user) → assistant`. Removing them
+   exposes runs of consecutive assistant messages, which alternation-requiring providers reject — a
+   stricter risk than the one marker-per-round growth they cost (about 200 bytes each, bounded by
+   `maxRounds` per human message, and they accumulate across messages). Their body is constant (`<todo_loop_continue/>`), so a marker left in
+   history cannot claim the loop is on some other round. With the kill switch set the hook rewrites
+   nothing, because a disabled extension must not touch the request.
+3. **Two different tails are in play, and only one of them is constrained.** pi's boundary checks the
+   *persisted projection* when `turn_end` proposes `continue: true`; the appended marker is what
+   satisfies that check for this extension (`_buildBoundaryContext().canContinue`, computed from the
+   committed drafts — any non-assistant final projected message would do, including a queued one). The
+   *provider request* built by the `context` hook is a different list: pi documents no constraint on its
+   final role, and a request ending on the assistant message is a normal continuation — the mechanism
+   used by `pi-invisible-continue`'s `/continue`
+   (<https://github.com/monotykamary/pi-invisible-continue>, not re-tested here). Conflating the two is
+   the mistake this item exists to prevent.
+4. **The block is appended only where it is needed, and it never doubles the tail.** Three
+   configurations get no block: `injectState: false`, a list with no open task, and the kill switch. In
+   the first two the request keeps whatever tail the history has (a marker, an assistant turn, or the
+   human's own message) and the model must call the todo tool's `list` action to learn the list — the
+   one place this extension asks for compliance instead of enforcing state. When a block is added it
+   replaces a tail marker, is merged into a human-role tail, and is appended only after an assistant or
+   tool tail. No request ending on an assistant message has been exercised against a provider in this
+   repository's testing; the live runs used the default configuration.
+5. **Returning a changed list rebuilds the request head.** pi documents that a `context` handler which
+   returns a different message list causes it to replay the current prompt sections and tool
+   declarations into one leading system message ahead of the returned list. The rebuild is lossless
+   (content appended, sections patched, tools resolved) but the head is not byte-identical to the
+   previous request, so a prompt cache keyed on the head can miss. Observed while reading pi 1.5.0's
+   extension runner; not measured in this repository.
+6. **Task state is read from the branch on every request, not cached in memory.** Loop state (counters,
+   anchor, pause) is in memory and therefore resets with the process. No `session_compact`
+   resync handler is needed, and a branch switch cannot leak another branch's tasks. The cost is one
+   backward walk of the active branch per request.
+7. **The marker `customType` is a stable literal, not a constant keyed to the package version.**
+   Sessions written by earlier builds keep filtering correctly after an upgrade.
+8. **Malformed session entries degrade to "no list".** A boundary handler that throws is reported and
+   the turn continues, but the loop would silently stop continuing; failing soft keeps the extension
+   inert instead of noisy.
+9. **`sendUserMessage` and `Agent.prompt` are deliberately not used.** `sendUserMessage` would add a
+   visible user-role message per continuation and pollute the transcript; calling the agent directly
+   bypasses `AgentSession` lifecycle handling (busy state, queuing, retry, abort).
+10. **The kill switch is checked in both hooks, not once at load.** Removing it or creating the file
+   takes effect on the next request, without `/reload`.
+11. **No dependency on `@earendil-works/pi-coding-agent`, and no peer declaration for it.** Nothing
+    here imports the package: the boundary is typed `pi: any` and contexts are typed structurally
+    (`SessionContext`), so the only manifest link to the host is `pi.extensions`. A `peerDependencies`
+    entry would assert a module dependency that does not exist and would have no effect regardless —
+    managed installs pass `--omit=peer` and disable peer resolution, and the loader performs no
+    compatibility check. The trade-off of dropping the type import: the compiler does not check event
+    payload shapes, so `npm test` and a real `pi -e` run carry that weight, and the tested pi version
+    is recorded in the table above rather than enforced.
+12. **A declared dependency on rpiv-todo's *persisted shape*, which is not its public API** (checked
+    against `@juicesharp/rpiv-todo` 2.15.0; the symbols named below are that version's). This
+    extension imports nothing from `@juicesharp/rpiv-todo` and therefore declares no dependency on it,
+    but it reads two representations the package writes: `custom` entries with
+    `customType: "rpiv-todo-state"`, and `todo` toolResult `details.tasks`. The package's own issues
+    describe `details` as extension-specific session data, so a change to that shape is not
+    guaranteed to appear in its semver. Consequences, accepted deliberately:
+    - the reader is written defensively (both shapes tried, `subject`/`content` accepted, malformed
+      entries treated as "no list") so a drift degrades to inert rather than throwing in a boundary;
+    - the tested version is recorded above, not enforced;
+    - the parser is duplicated rather than imported. `@juicesharp/rpiv-todo/state/replay.ts` does
+      export `replayFromBranch` and `isTaskDetails`, but a peer import would resolve to nothing under
+      pi's `--omit=peer` installs, and a declared dependency would make pi install a second nested
+      copy of the extension — which registers a duplicate `todo` tool.
+    - failure is currently indistinguishable from "the agent never called `todo`": both report
+      `stopped: no list` in `/todoloop`. Making those cases distinguishable is the next diagnostic
+      improvement, not a compatibility fix;
+    - a *newer* entry whose `tasks` is malformed is skipped in favour of an older valid one, so after a
+      shape change the reader serves the list as of the change. Not treated as authoritative-empty on
+      purpose: an errored `todo` call carries no `tasks`, and reading that as "list clear" would stop the
+      loop on a failed tool call.
+
+13. **The anchor skips user-role messages that carry a `customType`** _(silent)_. `anchorFromEntry`
+    ignores any `role: "user"` message with a string `customType`, which covers this extension's own
+    marker, another continuation extension's hidden resume message, and a command expansion that carries
+    one. The alternative — narrowing the skip to our own marker type — would let another extension's
+    hidden message move the anchor on every continuation and re-arm the budget each round, which defeats
+    the cap; the cost of the broad skip is that such a message does not reset the budget either. That is
+    one budget for one message, self-healing on the next plain message and visible in
+    `/todoloop`'s `anchor` line.
+
+14. **The loop's counters are not reconstructible from the session file** _(silent)_. A `turn_end`
+    handler is handed `outcome`, `entries` and `continue`; what a `-p`/JSON run persists for the event
+    carries only `{type, message, toolResults}`. A session file therefore shows which continuations happened and
+    when, not how many rounds or strikes were left, nor why the loop stopped; that is only visible live
+    through `/todoloop`. Two runs that end for different reasons can look identical on disk.
+
+15. **Three user-role tails cannot take a merge, so the block becomes a second user message there.**
+    pi rebuilds the content of `bashExecution`, `branchSummary` and `compactionSummary` from their own
+    fields and ignores `content`, so writing the block into one of them would delete it. Those three
+    get a separate user message instead, which means the request briefly has two user-role messages in a
+    row. Accepted deliberately: a compaction summary is exactly when the model most needs the list, and
+    losing it silently is worse than an adjacency that providers merge anyway.
+
+16. **The reader walks `getBranch()`, which is not the model-visible context.** pi's compaction-aware
+    projection is `buildContextEntries()`, and a `context_edit` can hide an entry from future model
+    context while it stays on the branch. Reading the branch therefore means the extension can report a
+    task list the model cannot see — after a compaction, or after another extension edited context. Kept
+    deliberately: the newest persisted todo state is the right answer for the loop's counters, and
+    reading the projected context instead would make the list vanish mid-run, which is the failure this
+    package exists to prevent.

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@dumbmice/pi-todo-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@dumbmice/pi-todo-loop",
+	"version": "0.1.0",
+	"description": "Keep pi working while a todo list still has open tasks, and keep that list in context across compaction.",
+	"type": "module",
+	"license": "MIT",
+	"author": {
+		"name": "DumbMice",
+		"email": "bangchengyang@hotmail.com"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi-coding-agent",
+		"todo",
+		"task-list",
+		"continuation",
+		"agentic-loop",
+		"compaction",
+		"deepseek",
+		"rpiv-todo"
+	],
+	"homepage": "https://github.com/DumbMice/pi-todo-loop#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DumbMice/pi-todo-loop.git"
+	},
+	"bugs": "https://github.com/DumbMice/pi-todo-loop/issues",
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"files": [
+		"src",
+		"scripts",
+		"tsconfig.json",
+		"docs",
+		"README.md",
+		"AGENTS.md",
+		"CONTRIBUTING.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "node --experimental-strip-types --no-warnings --test test/*.test.ts",
+		"typecheck": "tsc -p tsconfig.json",
+		"pack:check": "node scripts/check-pack.mjs",
+		"prepublishOnly": "npm test && npm run typecheck && npm run pack:check",
+		"pretest": "node -e \"const [a,b]=process.versions.node.split('.').map(Number); if(a<22||(a===22&&b<6)){console.error('@dumbmice/pi-todo-loop tests need Node >= 22.6, but node '+process.versions.node+' is first in PATH.\\nPut a newer node first, for example pi own node:\\n  ~/.local/share/pi-node/current/bin'); process.exit(1)}\""
+	},
+	"engines": {
+		"node": ">=22.19"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.5",
+		"typescript": "^5.9.3"
+	}
+}

package/scripts/check-pack.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Verify the published tarball actually contains what the package promises.
+ *
+ * `npm pack --dry-run` prints a file list and exits 0 even when `files` matches
+ * nothing, so dropping "src" from the manifest used to pass CI while shipping a
+ * package whose `pi.extensions` entry point does not exist. This asserts the
+ * entry point, the docs and the licence are in the tarball.
+ */
+
+import { execFileSync } from "node:child_process";
+import { firstPack } from "./pack-json.mjs";
+
+const REQUIRED = [
+	"src/index.ts",
+	"src/loop.ts",
+	"src/state.ts",
+	"src/inject.ts",
+	"src/config.ts",
+	"docs/pi-api-alignment.md",
+	"README.md",
+	"AGENTS.md",
+	"CONTRIBUTING.md",
+	"CHANGELOG.md",
+	"LICENSE",
+	"tsconfig.json",
+];
+
+const FORBIDDEN = ["test", "test/", ".github", "node_modules", "package-lock.json"];
+
+const raw = execFileSync("npm", ["pack", "--dry-run", "--json"], { encoding: "utf8" });
+const tarball = firstPack(JSON.parse(raw));
+if (!tarball || !Array.isArray(tarball.files)) {
+	console.error("pack check failed — npm pack produced no file list");
+	process.exit(1);
+}
+const files = new Set(tarball.files.map((file) => file.path));
+
+const missing = REQUIRED.filter((path) => !files.has(path));
+if (missing.length > 0) {
+	console.error(`pack check failed — missing from the tarball:\n  ${missing.join("\n  ")}`);
+	const sample = [...files].slice(0, 20).join("\n  ");
+	console.error(`\nfiles present (${files.size}):\n  ${sample}`);
+	process.exit(1);
+}
+
+const entry = JSON.parse(execFileSync("node", ["-p", "JSON.stringify(require('./package.json').pi)"], { encoding: "utf8" }));
+for (const declared of entry.extensions ?? []) {
+	const path = declared.replace(/^\.\//, "");
+	if (!files.has(path)) {
+		console.error(`pack check failed — pi.extensions declares ${path}, which is not in the tarball`);
+		process.exit(1);
+	}
+}
+
+const leaked = [...files].filter((path) => FORBIDDEN.some((bad) => path === bad || path.startsWith(`${bad}/`)));
+if (leaked.length > 0) {
+	console.error(`pack check failed — dev-only paths in the tarball:\n  ${leaked.join("\n  ")}`);
+	process.exit(1);
+}
+
+console.log(`pack ok: ${files.size} files, entry point and docs present, no dev paths`);

package/scripts/pack-json.mjs

@@ -0,0 +1,33 @@
+/**
+ * Read `npm pack --json`, whose shape changed between npm majors.
+ *
+ * npm 10 returns an array of tarball records; npm 11 returns an object keyed by
+ * package name. The publish workflow upgrades npm, so both shapes appear in practice
+ * and code that destructures `[0]` breaks on the newer one.
+ */
+
+import { execFileSync } from "node:child_process";
+
+/** Normalise either shape to a list of tarball records. */
+export function packEntries(value) {
+	if (Array.isArray(value)) return value.filter((entry) => entry && typeof entry === "object");
+	if (value && typeof value === "object") {
+		return Object.values(value).filter((entry) => entry && typeof entry === "object");
+	}
+	return [];
+}
+
+/** The first packed record, or undefined. */
+export function firstPack(value) {
+	return packEntries(value)[0];
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	const raw = execFileSync("npm", ["pack", "--dry-run", "--json"], { encoding: "utf8" });
+	const record = firstPack(JSON.parse(raw));
+	if (!record || typeof record.filename !== "string") {
+		console.error("pack-json: npm pack produced no tarball record");
+		process.exit(1);
+	}
+	console.log(record.filename);
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+/**
+ * Config loading. A missing, unreadable, or malformed file falls back to the
+ * defaults: this extension must never be the reason a turn fails.
+ */
+
+import { readFileSync } from "node:fs";
+import { DEFAULTS, type LoopConfig } from "./loop.ts";
+
+export { DEFAULTS };
+
+function coerce(raw: unknown): Partial<LoopConfig> {
+	if (typeof raw !== "object" || raw === null) return {};
+	const record = raw as Record<string, unknown>;
+	const out: Partial<LoopConfig> = {};
+
+	// Clamped, not just validated: a hostile or typo'd config must not be able to
+	// defeat the caps it configures (`maxRounds: 1e9` would otherwise be honoured).
+	const bounded = (value: unknown, ceiling: number): number | undefined =>
+		typeof value === "number" && Number.isFinite(value) && value >= 1
+			? Math.min(Math.floor(value), ceiling)
+			: undefined;
+
+	const maxRounds = bounded(record.maxRounds, 1_000);
+	if (maxRounds !== undefined) out.maxRounds = maxRounds;
+
+	const maxStrikes = bounded(record.maxStrikes, 100);
+	if (maxStrikes !== undefined) out.maxStrikes = maxStrikes;
+
+	if (typeof record.injectState === "boolean") out.injectState = record.injectState;
+
+	const maxInjectedTasks = bounded(record.maxInjectedTasks, 50);
+	if (maxInjectedTasks !== undefined) out.maxInjectedTasks = maxInjectedTasks;
+
+	return out;
+}
+
+export function mergeConfig(raw: unknown): LoopConfig {
+	return { ...DEFAULTS, ...coerce(raw) };
+}
+
+export function loadConfig(path: string): LoopConfig {
+	try {
+		return mergeConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		// A fresh copy: the shared object must never be mutable by a caller.
+		return { ...DEFAULTS };
+	}
+}