Adr 0004

.changeset/adr-0004-abort-after-final-yield.md

@@ -0,0 +1,7 @@
+---
+"loop-extender": patch
+---
+
+SPEC §9.3: `run()` now honors the abort-after-final-yield carve-out. An `AbortSignal` that aborts after the final `Output` has been yielded (via `stop: true` or `maxIterations` reached) but before the generator settles via `{ done: true }` now produces the abort error on the next generator interaction (`.next()`, `.return()`, or `.throw()`), with `LOOPX_TMPDIR` cleanup running before the abort error surfaces.
+
+Previously, the wrapper returned by `run()` would silently complete in this window, ignoring the abort. The wrapper now tracks the post-final-yield state and dispatches abort cleanup-then-throw on the next consumer interaction. First-observed-wins precedence is preserved: a prior consumer `.return()` / `.throw()` retains its silent-completion outcome and is not displaced by a later abort. For `.throw(consumerErr)` in this window, the abort error displaces the consumer-supplied error (per SPEC §9.3).

.changeset/adr-0004-auto-install-foundational.md

@@ -0,0 +1,13 @@
+---
+"loop-extender": minor
+---
+
+SPEC 10.10: implement post-commit auto-install of workflow dependencies.
+
+After a successful commit phase, `loopx install` now runs `npm install` once per committed workflow with a top-level `package.json`, sequentially (npm children do not overlap), with cwd set to the workflow directory and `process.env` inherited unchanged. Before each spawn, loopx checks `.gitignore` and synthesizes one containing `node_modules` if absent (existing regular files are left unchanged; non-regular entries — symlink, directory, FIFO, socket, etc. — are recorded as safeguard failures, skip `npm install` for that workflow, and contribute to a final aggregate failure report on stderr).
+
+`--no-install` (already parsed at the CLI in a previous change) is now wired through to suppress both `npm install` invocation and `.gitignore` synthesis.
+
+Workflows without a top-level `package.json` are skipped silently. Malformed `package.json` (unreadable, invalid JSON, invalid loopx semver range, or non-regular path) emits at most one warning per workflow per install operation (deduped against preflight warnings) and skips auto-install + safeguard for that workflow.
+
+`npm install` non-zero exit and spawn failure (`npm` not on PATH) both record into the aggregate accumulator and cause `loopx install` to exit 1 at end of pass; partial `node_modules/` and committed workflow files are not rolled back.

.changeset/adr-0004-cjs-rejection-loader-hook.md

@@ -0,0 +1,13 @@
+---
+"loop-extender": patch
+---
+
+SPEC §6.3 CommonJS rejection now applies uniformly across all four JS/TS script extensions (`.js`, `.ts`, `.tsx`, `.jsx`). Previously, scripts using `module.exports = X` or `exports.foo = X` in a `.ts`/`.tsx`/`.jsx` workflow file silently ran on Node — defeating the SPEC §6.3 contract that CommonJS syntax must fail at execution time.
+
+The loopx custom loader-hook now intercepts `.ts`/`.tsx`/`.jsx` files in `.loopx/` directories, transforms them via esbuild (TS types stripped, JSX expanded to `React.createElement` per the existing classic-transform contract) without enabling esbuild's CJS-shim wrapper, and feeds the result to Node as a true ES module. Any reference to `module`, `exports`, or `require` then throws `ReferenceError` at evaluation time.
+
+`require()` rejection was already enforced for all four extensions (`.js` via the existing loader-hook ESM force; `.ts`/`.tsx`/`.jsx` via the auto-injected `.loopx/package.json {"type":"module"}` from `bin-path.ts` and Bun's `--define require:null`).
+
+`esbuild` is now declared as an explicit runtime dependency of `loop-extender` (previously transitive via `tsx`).
+
+This affects only workflow scripts that contained CommonJS syntax — those scripts now fail at execution time as the SPEC requires. Workflow scripts using ESM syntax (`import` / `export`) continue to work unchanged.

.changeset/adr-0004-cli-first-trigger-wins.md

@@ -0,0 +1,7 @@
+---
+"loop-extender": patch
+---
+
+CLI signal handler now honors SPEC §7.2 first-observed-wins: when a second signal arrives after the first (e.g., SIGTERM during cleanup of a prior SIGINT), the surfaced exit code stays anchored at the first signal's `128 + N` value rather than being overwritten by the second. Previously a SIGTERM during the cleanup of a SIGINT-driven termination would shift the exit code from 130 to 143; now it correctly stays at 130.
+
+This affects the rare case where two close-together signals reach loopx during a single run; everyday SIGINT/SIGTERM handling is unchanged.

.changeset/adr-0004-duck-signal-aborted-true-non-compatible-shape.md

@@ -0,0 +1,14 @@
+---
+"loop-extender": patch
+---
+
+ADR-0004 §9.3 / §9.5: a duck-typed `options.signal` whose `addEventListener` registration throws is now correctly surfaced as an option-snapshot error, even when the signal also reports `aborted: true`.
+
+Previously, `runWithInternal` short-circuited on `snap.signal.aborted === true` and skipped the `addEventListener` registration entirely — meaning a duck signal of the form `{ aborted: true, addEventListener() { throw } }` would route through the abort-precedence pathway and surface an `AbortError`, mis-categorizing the contract violation as an abort outcome.
+
+Two coupled changes restore SPEC §9.3 / §9.5 conformance:
+
+- Always invoke `signal.addEventListener("abort", listener, { once: true })` at call-site capture, regardless of `aborted` value, so the registration-throws case is detected. This honors SPEC §9.5's "must be callable and returns without throwing when loopx invokes it" wording — loopx must invoke `addEventListener` to verify the contract, and per the `aborted: true` × non-compatible-shape carve-out, that verification must happen even when `aborted: true`.
+- When registration throws, clear the captured `snap.signal` so the downstream abort-precedence check in `runInternal` does not mistake `aborted: true` on a non-compatible signal as grounds to surface an abort error. The captured `snap.error` then surfaces as an ordinary option-snapshot error via the standard pre-iteration error path.
+
+Behavior for valid duck signals is unchanged: the `addEventListener` is now invoked unconditionally during snapshot capture (instead of only when `aborted: false`), but real `AbortSignal` instances and well-formed duck signals do not observe a difference because `addEventListener` succeeds and the `aborted: true` branch then enters the abort-precedence pathway as before.

.changeset/adr-0004-env-subcommand-grammar-edges.md

@@ -0,0 +1,14 @@
+---
+"loop-extender": patch
+---
+
+SPEC 4.3 / 8.1 / 12: `loopx env list` now prints parser warnings to stderr, and `loopx env set / remove / list` reject extra positionals as usage errors.
+
+Previously:
+- `loopx env list` parsed the global env file with `parseEnvFile` (which produces warnings for invalid lines) but discarded the returned warnings array, so a malformed line like `1BAD=val` was silently dropped from the listing with no diagnostic. SPEC 8.1 specifies invalid lines are "ignored with a warning to stderr."
+- `loopx env list extra`, `loopx env set FOO bar extra`, and `loopx env remove FOO extra` all silently ignored the trailing positional and proceeded with the leading well-formed grammar — a buggy impl that committed `FOO=bar` despite an unrecognized 4th argument. SPEC 4.3 enumerates the env subcommand grammar as exactly `set <name> <value>` / `remove <name>` / `list` (no operands), and SPEC 12's usage-error contract requires exit 1 + a stderr usage error for parser-level surface failures.
+
+After the fix:
+- `loopx env list` emits `Warning: Line N: invalid key name: <key>` (or `Warning: Line N: missing '=' separator: <line>`) to stderr per malformed line — the same warning class as `loopx run` already emits when loading the global env file. Well-formed entries are still listed on stdout, the listing is still sorted, and exit code is still 0 (warnings are non-fatal).
+- `loopx env list extra` / `loopx env set FOO bar extra` / `loopx env remove FOO extra` exit 1 with `Error: loopx env <subcmd>: unexpected extra positional '<arg>'` on stderr; no env-file mutation occurs (the failure short-circuits before `envSet` / `envRemove` / `envList` is invoked).
+- `loopx env` (no subcommand), `loopx env set` / `set FOO` (missing operands), `loopx env remove` (missing name), and `loopx env unknown` (unrecognized subcommand) continue to be usage errors (unchanged).

.changeset/adr-0004-inst-116o-active-child-prior-failure-suppression.md

@@ -0,0 +1,13 @@
+---
+"loop-extender": patch
+---
+
+SPEC §10.10 / §7.3: SIGINT/SIGTERM arriving during an active `npm install` child for a workflow processed AFTER a prior workflow's auto-install failure now correctly suppresses the not-yet-emitted aggregate failure report (resolving P-0004-05's active-child × prior-failure-suppression sentence).
+
+Previously, the auto-install pause-seam dispatch for the `child-active-after-failure` window was declared but had no dispatch site — when SIGINT/SIGTERM arrived during the second-processed workflow's npm child window with a prior-workflow failure already recorded into the aggregate accumulator, the surfaced behavior was undefined relative to the SPEC contract.
+
+The `runAutoInstall` spawn-and-wait flow in `install.ts` is now split across two awaits: spawn synchronously + register exit handlers, optionally pause for the `child-active-after-failure` seam (TEST-SPEC §1.4), then await the child-exit promise. When a signal arrives during the pause, the existing CLI signal handler forwards the signal to the child's process group, the child dies, the exit promise rejects with NPM_SIGNAL, the catch branch's signal-suppression guard suppresses the per-workflow failure entry, and the end-of-pass signal-suppression guard returns 0 BEFORE the aggregate report is emitted.
+
+A noop `.catch(() => {})` is attached to the spawn-exit promise immediately after construction to suppress Node 25's fatal-unhandled-rejection behavior when the child exits during the seam pause (rejection lands before the await attaches its handler). The await still throws normally; only the fatal warning is suppressed.
+
+Closes the LAST gap in the SPEC §10.10 / §7.3 T-INST-116 cluster — the entire signal × auto-install matrix (active-child × {no-prior-failure, prior-failure}, no-active-child × seven ordinal windows, SIGKILL escalation, process-group forwarding, multi-workflow no-further-processing) is now in place.

.changeset/adr-0004-loopx-tmpdir.md

@@ -0,0 +1,11 @@
+---
+"loop-extender": minor
+---
+
+ADR-0004 §7.4: scripts now receive a per-run `LOOPX_TMPDIR` protocol-injected environment variable pointing at a freshly-created temporary directory, and loopx automatically cleans it up on every terminal outcome (normal completion, script error, invalid `goto`, abort, signal, consumer cancellation).
+
+Per SPEC §7.4, the directory is created via `mkdtemp(<os.tmpdir()>/loopx-)` with mode `0700` and an identity fingerprint captured for cleanup safety. The same value is injected into every spawned script in the run (starting target, intra- and cross-workflow `goto`, loop reset). Files written there persist within the run and are removed when loopx exits.
+
+Cleanup is identity-fingerprint-matched and best-effort — a recorded `LOOPX_TMPDIR` whose `lstat` no longer matches what loopx created (renamed, replaced, or different inode) is left in place with a single stderr warning rather than recursively removed. Cleanup runs at most once per resource and emits at most one warning regardless of how many terminal triggers race.
+
+**For workflow scripts**: read `$LOOPX_TMPDIR` (Bash) or `process.env.LOOPX_TMPDIR` (JS/TS) for a writable scratch location that is guaranteed to exist for the duration of the run and to be cleaned up afterwards. Use this for cross-workflow `goto` rendezvous data or any per-run temp state.

.changeset/adr-0004-no-install-cli-flag.md

@@ -0,0 +1,9 @@
+---
+"loop-extender": patch
+---
+
+SPEC 4.2 / 10.10 / 11.3: recognize `--no-install` as a boolean install-scoped flag in the install CLI parser, and list it in `loopx install -h` / `--help` output.
+
+`parseInstallArgs` now accepts `--no-install` (no operand) with duplicate-flag rejection (`Error: duplicate --no-install flag`). The `-h` / `--help` short-circuit suppresses both the duplicate-flag error and any source acquisition (no network activity, `.loopx/` untouched). Common single-character candidates (`-n`, `-N`, `-i`, `-I`) remain rejected as unknown install-scoped short flags — `--no-install` has no short form per SPEC 4.2.
+
+The flag's behavioral effect (suppressing auto-install of workflow dependencies) is wired only at the parser layer in this change; the auto-install pipeline itself is a separate larger work-item per Spec 10.10.

.changeset/adr-0004-non-string-loopx-version-warning.md

@@ -0,0 +1,14 @@
+---
+"loop-extender": patch
+---
+
+SPEC 3.2: workflow-level version checking now correctly warns when `dependencies.loopx` or `devDependencies.loopx` is a non-string value (e.g., a JSON number).
+
+Previously, a workflow `package.json` like `{ "dependencies": { "loopx": 42 } }` was silently treated as if no `loopx` declaration existed — no warning fired and the version check was skipped without diagnostics. Per SPEC 3.2's "Valid JSON but `loopx` version field contains an invalid semver range: A warning is printed to stderr", any value that is not a valid semver range (including non-string types, since semver ranges are strings) must produce the same `invalid-semver` warning class.
+
+The fix applies symmetrically to:
+- the runtime workflow-version check (first entry into a workflow during a loop run)
+- the install-time preflight check (`loopx install` `dependencies.loopx` validation)
+- the post-commit auto-install pass (malformed-`package.json` skip)
+
+`peerDependencies.loopx` and `optionalDependencies.loopx` remain fully invisible at the workflow level, even when malformed, per SPEC 3.2's enumeration of checked fields. Likewise, an invalid range on a non-`loopx` dependency entry is ignored (the check reads only `dependencies.loopx` and `devDependencies.loopx`).

.changeset/adr-0004-pre-first-next-carve-out.md

@@ -0,0 +1,9 @@
+---
+"loop-extender": patch
+---
+
+SPEC §9.1: implement the pre-first-`next()` consumer-cancellation carve-out for `run()`.
+
+When the consumer cancels the iterator BEFORE invoking `.next()` for the first time — by calling `.return(value)`, `.throw(err)`, or via `await using` (Symbol.asyncDispose) — the wrapper now follows standard ES async-generator semantics: `.return(value)` settles with `{ value, done: true }`, `.throw(err)` rejects with the consumer-supplied error. The loop body is never entered, no pre-iteration step runs, no captured signal is consulted (even an already-aborted signal does not surface an abort error), and every captured pre-iteration error (option-snapshot, target validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation, version-check warnings) is suppressed.
+
+Previously, `.throw()` as a first interaction silently swallowed the consumer-supplied error by routing through `gen.return(undefined)`. The fix introduces a `bodyEntered` flag set inside `wrapper.next()` before awaiting the inner generator, so subsequent `.return()` / `.throw()` calls correctly distinguish pre-first-`next()` (carve-out) from post-first-`next()` (silent completion) cancellation.

.changeset/adr-0004-pre-iteration-signal-wins.md

@@ -0,0 +1,7 @@
+---
+"loop-extender": patch
+---
+
+CLI now honors SPEC §7.3 pre-iteration signal-wins precedence: SIGINT/SIGTERM observed by loopx during the pre-iteration window (target validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) wins over any non-signal pre-iteration failure that would otherwise have surfaced. loopx exits with `128 + N` and suppresses the displaced failure error rather than printing it as the fatal-exit reason.
+
+Previously, signal handlers were installed only after all pre-iteration steps completed, so a SIGINT delivered during pre-iteration would either be uncaught (default POSIX termination) or, if it raced past pre-iteration, lose the precedence contest with the failure. Now SIGINT/SIGTERM during a missing env file, missing workflow, invalid target, missing script, missing default `index`, missing `.loopx/`, or tmpdir creation failure all surface the signal exit code (130 / 143) per spec.

.changeset/adr-0004-project-root-cwd-and-workflow-dir.md

@@ -0,0 +1,9 @@
+---
+"loop-extender": minor
+---
+
+ADR-0004: scripts now run with `LOOPX_PROJECT_ROOT` as their working directory (not the workflow directory), and a new `LOOPX_WORKFLOW_DIR` protocol-injected env variable exposes the workflow directory.
+
+This is the foundational ADR-0004 §6.1 change. Previously, every spawned script's cwd was the workflow directory (e.g., `.loopx/ralph/`). Per SPEC §6.1, that contract is now project-root-unified — every script (starting target, intra- and cross-workflow `goto`, loop reset) spawns with cwd = `LOOPX_PROJECT_ROOT`. Scripts that need the workflow directory should read `LOOPX_WORKFLOW_DIR`, which is injected into every spawn's environment alongside `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, and `LOOPX_WORKFLOW`. Bash scripts can rely on the normative `dirname "$0" == LOOPX_WORKFLOW_DIR` equality (SPEC §6.2).
+
+**Migration:** any workflow script that did `cat ./helper.sh` (relying on cwd = workflow dir) must use `cat "$LOOPX_WORKFLOW_DIR/helper.sh"` instead.

.changeset/adr-0004-run-dashdash-rejection.md

@@ -0,0 +1,13 @@
+---
+"loop-extender": patch
+---
+
+SPEC 4.1 / 4.2 / 11.2 / 12: `loopx run` now rejects `--` as an unrecognized token wherever it appears, instead of silently consuming it as an end-of-options marker.
+
+Previously, the `run` parser accepted `--` as a separator and treated the next argv as the target — so `loopx run -- ralph`, `loopx run -n 1 -- ralph`, and `loopx run ralph --` all succeeded (or failed only because of unrelated reasons). SPEC 4.1 explicitly states that `--` is **not** an end-of-options marker for `run` and is rejected wherever it appears outside the `-h` / `--help` short-circuit, and SPEC 12 enumerates several `--` forms (`loopx run -- ralph`, `loopx run -n 1 -- ralph`, `loopx run ralph -- name=value`) as usage errors.
+
+After the fix:
+- `loopx run -- ralph`, `loopx run -n 1 -- ralph`, `loopx run ralph -- name=value`, `loopx run --`, `loopx run ralph --` — all exit 1 with `Error: unrecognized token '--' …` on stderr.
+- `loopx run -e -- ralph`, `loopx run ralph -e --`, `loopx run -n -- ralph`, `loopx run ralph -n --` — all exit 1 citing `--` as the offending token. Previously these would either consume `--` as the `-e` operand (loading a file literally named `--` as the env file) or surface an "invalid `-n` operand" error treating `--` as a non-integer value; both behaviors violated SPEC 4.1's "wherever it appears" rule.
+- `loopx run -h -- ralph`, `loopx run -- -h`, `loopx run -- --help` — help short-circuit still fires (unchanged).
+- The shell env prefix (`adr=0003 loopx run ralph`) remains the sole CLI surface for per-run parameterization, as documented in SPEC 11.2 / 13.

.changeset/adr-0004-run-first-trigger-wins.md

@@ -0,0 +1,7 @@
+---
+"loop-extender": patch
+---
+
+`run()` / `runPromise()` consumer-cancellation methods (`.return()`, `.throw()`, `[Symbol.asyncDispose]`) now honor SPEC §7.2 first-observed-wins for the abort-vs-consumer-cancellation race. When the run's `AbortSignal` is already aborted at the time `.return()` / `.throw()` is called, the in-flight iteration's abort error surfaces to the consumer (via the for-await loop or `gen.next()` rejection) instead of being silenced by the consumer-cancellation contract. When `.return()` / `.throw()` is observed first (no prior abort), the previous silent-clean-completion behavior is preserved.
+
+This affects the rare case where an external abort and a consumer cancellation race for the same run; everyday `.return()` / `.throw()` cancellation flows are unchanged. SPEC §9.3 post-final-yield-abort handling is also unchanged.