instar 1.3.241 → 1.3.243

package/upgrades/double-send-route-guard.eli16.md

@@ -0,0 +1,26 @@
+# ELI16 — Double-send route guard
+
+Some server routes can accidentally send an HTTP response and then keep running. If later code tries
+to send another response, Express throws the familiar "Cannot set headers after they are sent to the
+client" error. The original bug is usually a missing `return` after an early `res.json()` or
+`res.status(...).json()` branch.
+
+This change adds two protections.
+
+First, the server now installs a duplicate-response guard before routes run. If a handler has already
+committed a response and later tries to send another JSON/send-style response, the guard logs the
+duplicate with a stack and suppresses the second send instead of letting it throw through the request
+path.
+
+Second, the central Express error handler now checks whether the response was already sent. If an
+error arrives after a route has already replied, it logs the late error with stack context and returns
+without trying to send a second 500 response.
+
+There is also a source-level audit test for the classic missing-return shape: an early branch that
+sends a response without returning, followed by a later direct response in the same route handler. The
+test includes a bad fixture to prove the detector catches the pattern, then scans the current server
+route sources to keep that shape out.
+
+This does not change successful API responses. It only changes what happens after code tries to send
+again after a response is already committed: the server logs the mistake and preserves the first
+response.

package/upgrades/side-effects/apprenticeship-manual-cycle-write-path.md

@@ -0,0 +1,52 @@
+# Side-Effects Review - Apprenticeship manual cycle write path
+
+**Version / slug:** `apprenticeship-manual-cycle-write-path`
+**Date:** 2026-06-03
+**Author:** codey
+
+## Summary of the change
+
+Current `JKHeadley/main` already had `POST /apprenticeship/cycles`, so this change does not add a second route. It finishes the manual/overseer write path around that existing route:
+
+- `src/server/routes.ts` now validates that manual cycle POST bodies are objects and that `channel`, when present, is one of the four store-supported values.
+- `src/server/CapabilityIndex.ts` now surfaces the apprenticeship cycle endpoints in `/capabilities`.
+- `src/scaffold/templates.ts` adds a CLAUDE.md awareness blurb for manual cycle recording.
+- `src/core/PostUpdateMigrator.ts` mirrors that blurb for existing agents that do not yet have the Apprenticeship Program section.
+- `src/data/builtin-manifest.json` is regenerated after the route/source changes.
+- `upgrades/next/apprenticeship-manual-cycle-write-path.md` records the release-note fragment required by the publish gate.
+- Route and capability tests cover strict channel validation, channel persistence, manual overseer cycle capture, and discovery.
+
+## Side effects and blast radius
+
+The only behavior change on the write path is stricter HTTP validation. A malformed manual request with an unknown channel now receives HTTP 400 instead of being written as `unknown`. The lower-level `ApprenticeshipCycleStore.record()` behavior is unchanged, so legacy rows and automated/non-HTTP callers still normalize invalid or missing channels to `unknown`.
+
+The route remains persistence-only. It does not mutate apprenticeship instance status, does not run lifecycle gates, and does not decide whether a cycle was good. It only writes the row to the cycle store, and existing role-coverage logic interprets those rows afterward.
+
+Capability discovery changes only metadata returned by `/capabilities`; no new auth surface or prefix classification is introduced. `/apprenticeship` was already a public capability prefix, so no `INTERNAL_PREFIXES` entry is needed or appropriate.
+
+The template and migrator changes alter generated/updated CLAUDE.md guidance text. They do not execute operational work. Existing installs that already have an Apprenticeship Program section are still protected by the current idempotency marker and will not be double-patched by this migration.
+
+## Risks considered
+
+- **Breaking automated mentor ticks:** low. The automated call site writes through the store, not the HTTP route, and does not provide a channel today. Store defaulting remains unchanged.
+- **Rejecting useful manual records because of a typo:** intentional. Manual/overseer HTTP writes should fail loudly when the channel is not one of the program-defined channels.
+- **Capability configured status drift:** low. The capability now reports configured when either the instance program or cycle store is wired, matching the fact that cycle routes can be alive independently of the instance object in tests and boot wiring.
+- **Template guidance becoming stale:** medium over time. This is mitigated by listing the same enum values exported by the store today and keeping the text concise.
+
+## Test evidence
+
+Focused verification:
+
+- `npx vitest run tests/integration/apprenticeship-routes.test.ts tests/unit/CapabilityIndex.test.ts tests/e2e/apprenticeship-lifecycle.test.ts`
+- Result: 3 files passed, 31 tests passed.
+
+Planned final checks before push:
+
+- `pnpm lint`
+- `pnpm build`
+- `node dist/cli.js dev:preflight`
+- `pnpm test:smoke`
+
+## Rollback cost
+
+Rollback is a normal code revert. Reverting restores the previous permissive HTTP behavior, removes the capability endpoint entries, and removes the new generated/migrated awareness line. No database migration is introduced, and no existing cycle rows need transformation.

package/upgrades/side-effects/double-send-route-guard.md

@@ -0,0 +1,66 @@
+# Side-Effects Review — Double-send route guard
+
+Slug: `double-send-route-guard`
+
+## Summary
+
+Adds a last-resort Express duplicate-response guard and hardens the shared error handler against
+late errors after a response has already been committed. Adds regression coverage for both runtime
+paths and a source-level audit test for the classic missing-return route pattern.
+
+## Decision inventory
+
+- New runtime decision: if `res.headersSent` or `res.writableEnded` is already true, suppress a later
+  `res.json`, `res.send`, `res.sendStatus`, `res.redirect`, `res.download`, or `res.sendFile` call
+  and log it.
+- New error-handler decision: if an error reaches `errorHandler` after the response is committed, log
+  the late error and do not attempt a second 500 response.
+- New test-time decision: a route source audit flags a direct early branch response without a return
+  when a later direct handler response exists.
+
+## Over-block
+
+The guard only activates after the response is already committed. It does not block the first
+response, does not reject requests, and does not change status codes on normal paths. It may suppress
+a second response attempt that a caller previously saw as a thrown server error, but that second
+response was never valid HTTP behavior.
+
+## Under-block
+
+The guard does not make route fallthrough logically correct; it prevents the process/request path from
+throwing on the second send and preserves stack evidence. The source audit focuses on the high-signal
+classic pattern and intentionally does not try to prove every possible nested control-flow path.
+Reviewers still need to inspect unusual async flows.
+
+## Level-of-abstraction fit
+
+The runtime protection belongs in Express middleware because duplicate sends are a response-layer
+failure that can happen in any route. The source audit belongs in tests because it is a structural
+authoring guard, not a production decision point.
+
+## Signal vs authority
+
+The source audit is authority in CI for the narrow syntactic pattern it detects. The runtime guard is
+authority only over a response that is already committed; at that point there is no valid second
+response to authorize. It logs enough stack context for follow-up instead of silently hiding the
+underlying route bug.
+
+## Adjacent interactions
+
+- `requestTimeout` already checks `!res.headersSent`; this change does not alter timeout budgets.
+- Dashboard, auth, machine, and API routes are covered because the middleware is installed before
+  route registration.
+- Express error middleware keeps returning normal 500 JSON for errors before a response is committed.
+- Direct low-level `res.end()` is not monkey-patched to avoid interfering with Express internals
+  during legitimate first sends.
+
+## Rollback
+
+Rollback is straightforward: remove `duplicateResponseGuard` wiring, remove the middleware export,
+restore the old `errorHandler` implementation, and remove the two unit tests. No data migration,
+config migration, or user action is involved.
+
+## Evidence
+
+- `npx vitest run tests/unit/duplicate-response-guard.test.ts tests/unit/route-double-send-audit.test.ts`
+- `npx tsc --noEmit`