@aperant/framework 0.6.7 → 0.7.3

package/skills/apt-setup/SKILL.md

@@ -1111,6 +1111,34 @@ The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it do
 
 ## 4. Map Answers to Config
 
+**AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.7.2):** the
+following five fields are PER-DEVICE and MUST land in `.aperant/config.local.json`
+(gitignored), NOT the shared `.aperant/config.json`:
+- `verification.open_report` — covered in the "Auto-Open" mapping below.
+- `multi_model.cross_verification.tools` — covered in the "Cross-Verification" mapping below.
+- `preferences.date_format` — covered in the "Date Format" mapping below.
+- `preferences.time_format` — covered in the "Time Format" mapping below.
+- `preferences.quick_task_post_verify` — covered in apt-quick SKILL config block.
+
+All other fields (including `verification.evidence_capture`,
+`multi_model.cross_verification.enabled`, `multi_model.video_review.*`,
+`preferences.task_index`, every `orchestration.*` value) stay in shared
+`.aperant/config.json`.
+
+Implementation: use the framework's `writeLocalConfigField(targetDir, dotPath, value)`
+helper from `packages/framework/src/cli/config/load.mjs` (or its shell-out
+equivalent via `apt-tools config write . --local --key <dotpath> --value <json>`)
+for the five fields above. NEVER hand-roll `JSON.parse(readFileSync('.aperant/config.json'))`
+followed by `writeFileSync('.aperant/config.json', ...)` for these fields — it
+will land per-device data in the shared file and re-introduce the
+shared-config trap AUDIT-001 was designed to close.
+
+Reads of these fields anywhere in the framework MUST go through
+`loadMergedProjectConfig(targetDir)` or `readLocalOrSharedField(targetDir, dotPath)`
+so per-device overrides are honored.
+
+---
+
 Map the user's selections to config values:
 
 **Verify Mode:**
@@ -1180,13 +1208,16 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 
 ## 5. Write Config
 
-Write merged config to `.aperant/config.json`:
+Write merged config to two files per AUDIT-001 routing (see Step 4 block):
+
+- Shared `.aperant/config.json` — all project policy values (the bulk of the answers).
+- Per-device `.aperant/config.local.json` — the five AUDIT-001 fields enumerated in Step 4.
 
 ```bash
 mkdir -p .aperant
 ```
 
-Write the JSON file with 2-space indentation. Bump `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional).
+Write each JSON file with 2-space indentation. Bump shared `config.json`'s `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional). `config.local.json` is gitignored by `.aperant/.gitignore` — do not check it in.
 
 ## 6. Save as Global Defaults (Optional)
 

package/skills/apt-ship/SKILL.md

@@ -412,19 +412,30 @@ ci_watch_armed=$(echo "$ship_update" | jq -r '.ci_watch_armed // false')
 ci_watch_skip_reason=$(echo "$ship_update" | jq -r '.ci_watch_skip_reason // empty')
 ci_watch_host=$(echo "$ship_update" | jq -r '.ci_watch.host // "unknown"')
 ci_watch_deadline=$(echo "$ship_update" | jq -r '.ci_watch.deadline // empty')
+ci_watch_scheduler_handle=$(echo "$ship_update" | jq -r '.scheduler_handle // empty')
 host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
 ```
 
 **Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
 
-**Branch on the task-update envelope:**
+**Branch on the task-update envelope** (FRAMEWORK-BUG-018 — Track 1: distinguish state-recording from wake-registration):
 
-- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` non-empty** — emit:
 
   ```
   [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
   ```
 
+  This is the only honest "armed" case — a scheduler handle proves the wake is registered.
+
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` empty** — emit:
+
+  ```
+  [APT:ship] CI watcher state created (host: {ci_watch_host}). Register a wake-up to drive ticks: CronCreate every ~3min running '/apt:watch-ci --tick --pr {N}'. Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+  State is recorded but no scheduler is registered — the orchestrator MUST register a wake or ticks will never fire. Track 2 (auto-wake on arm) will populate `scheduler_handle` and route into the first branch instead.
+
 - **`ci_watch_armed=true` AND `host_cron=false`** — emit:
 
   ```
@@ -442,10 +453,11 @@ host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host
   On `Y` (or empty enter), call:
 
   ```bash
-  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  arm_envelope=$(node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli})
+  ci_watch_scheduler_handle=$(echo "$arm_envelope" | jq -r '.scheduler_handle // empty')
   ```
 
-  Then emit the same host-cron-aware success banner used for `ci_watch_armed=true`. On `N` or any other response, proceed silently to Section 8.
+  Then route into the same four-way logic above — branch 1 (armed with handle), branch 2 (state-created, needs wake), or branch 3 (host has no cron). On `N` or any other response, proceed silently to Section 8.
 
 - **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
 

package/skills/apt-spar/SKILL.md

@@ -129,14 +129,26 @@ If `--with` resolves to the same CLI as the host (e.g. `--with claude` when `hos
 
 Do NOT proceed; self-sparring is sycophancy by construction (the host cannot objectively challenge itself). This check runs after `host-detect` and before any partner availability check.
 
-**Partner unavailable.** If the resolved partner CLI binary or script is not on `$PATH` — or, for the codex-companion path, if `CLAUDE_PLUGIN_ROOT` is unset OR `${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs` does not exist — print a clean fallback and stop:
+**Partner transport ladder (FRAMEWORK-BUG-024).** Read `host.partner_transports.<partner>` from the host-detect envelope (`jq '.host.partner_transports.codex'`, etc.). Each partner has a 3-rung ladder evaluated in preference order — **MCP-first** for cleaner tool-call integration, with automatic fallthrough to plugin shim then raw CLI:
+
+1. **Rung 1 — MCP tool** (`mcp__<partner>-mcp__*`, e.g. `mcp__codex-mcp__codex`). Detected if the host exposes its deferred-tool manifest via `CLAUDE_MCP_DEFERRED_TOOLS` and the tool is registered. When `detected: "runtime-host-only"` the framework process cannot probe the host's tool registry from outside — treat as candidate and attempt the tool call; if the tool is genuinely unavailable in the host's visible registry, fall through to rung 2.
+2. **Rung 2 — Plugin shim** (`${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`). Codex only (claude / gemini have no plugin shim).
+3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini -m`).
+
+Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 60000ms, configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. Empirical: the Codex MCP `claude_code` tool has been observed to hang past 120s. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
+
+If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
 ```
-[apt:spar] partner `<id>` unavailable. Either:
-  - install the partner CLI (Codex: install the `codex` Claude Code plugin so `CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs` resolves; Claude: install the `claude` CLI on $PATH; Gemini: install the `gemini` CLI on $PATH)
-  - re-run with `--with <other-id>` to pick a different partner
+[apt:spar] partner `<id>` unavailable. Tried:
+  - MCP tool `mcp__<partner>-mcp__*`: <not loaded in this host | runtime-host-only + timed out at <ms>ms>
+  - Plugin shim `${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`: <missing reason>
+  - Raw CLI `<bin>` on $PATH: not found
+Install any one of the three or re-run with `--with <other-id>`.
 ```
 
+The failure message MUST name all three transports tried (`mcp`, `plugin shim`, `raw CLI`) so the user can pick the cheapest fix.
+
 Do NOT silently degrade to the host (sparring with yourself is sycophancy by construction).
 
 ## 4. Frame the Round
@@ -159,13 +171,26 @@ The frame is one shot per round — no multi-turn conversation with the partner
 
 **Wrap every partner Bash call with an explicit timeout** (default 90000ms, override via `--timeout-ms`). The empirical reason: the Codex MCP `claude_code` tool has been observed to hang past 120s while the `claude -p` CLI returns in seconds. A hung partner CLI must NOT stall the spar loop.
 
-The table below shows the canonical command shape; the actual invocation MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation.
-
-| Host | Command | Notes |
-|---|---|---|
-| `host=claude-code` (or `--with codex`) | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
-| `host=codex` (or `--with claude`) | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
-| `--with gemini` (any host) | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
+The table below shows the canonical command shape per (partner × rung); the actual invocation for shell-based rungs (plugin shim, raw CLI) MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation. The MCP rung is a structured tool call — no shell quoting concern applies.
+
+<!--
+  Future contributor: the `codex exec` flag below is taken from the precedent
+  at `packages/framework/skills/apt-pr-review/SKILL.md:1084`. Codex CLI flag
+  surface evolves; verify with `codex --help` at execution time and update
+  this table if the non-interactive invocation shape changes.
+-->
+
+| Partner | Rung | Command | Notes |
+|---|---|---|---|
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 60s timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
+| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
+| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. Verify with `codex --help`. |
+| claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 60s timeout + fallthrough rule. |
+| claude | plugin | n/a | No plugin shim exists for Claude. Skip this rung. |
+| claude | cli | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
+| gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 60s timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
+| gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
+| gemini | cli | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
 
 Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 90000).
 

package/skills/apt-update/SKILL.md

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Write"
-argument-hint: "apt:update"
+argument-hint: "apt:update [--from-source]"
 gates: []
 ---
 
@@ -90,6 +90,30 @@ npm install --prefix .aperant/deps @aperant/framework@<latest_version> --no-save
 
 On `npm 404` (`E404` in stderr) treat it as `not_published` and skip the kernel bump (proceed to step 3). On any other npm failure, surface the npm stderr verbatim and STOP — do NOT proceed to init with a half-installed kernel.
 
+## 1.6. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+
+When the user invokes `/apt:update --from-source` OR the route envelope's `update_check.reason` mentions `workspace source ahead of installed kernel`, the source of truth is the local `packages/framework/` workspace — NOT npm. This is the Aperant-contributor self-host case: a same-PR framework fix bumps the workspace `packages/framework/package.json:version` but the kernel under `.aperant/deps/node_modules/@aperant/framework/` still reflects the previous version. Step 1.5's `npm view` would fetch the published version (still the OLD one), so we must skip it.
+
+The reliable bump mechanism mirrors what `runKernelInstall` does today — `pnpm pack` produces a versioned tarball, then `npm install --prefix` consumes it. Symlinking is fragile across re-installs and `pnpm install --filter` doesn't relocate the published artifact into `.aperant/deps`.
+
+Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+
+```bash
+# 1. Pack the workspace source into a versioned tarball.
+cd <workspace-root>
+pnpm --filter @aperant/framework pack --pack-destination /tmp
+
+# 2. Install the tarball into the project's kernel root.
+cd <project-root>
+npm install --prefix .aperant/deps /tmp/aperant-framework-<version>.tgz --no-save --no-package-lock --no-audit --no-fund
+```
+
+Replace `<version>` with the workspace `package.json:version` you just read. The tarball name follows npm's `pack` convention (`@aperant/framework@X.Y.Z` → `aperant-framework-X.Y.Z.tgz`).
+
+If `--from-source` was passed but no `packages/framework/package.json` is found anywhere above the project root, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard step 1.5 npm path.
+
+Then proceed to step 3 to re-install the runtime files at the new kernel version. Skip step 4 (cache clear) — the cache is keyed on `latest_version` from npm, and a `--from-source` bump never wrote to it, so there's nothing to invalidate.
+
 ## 2. Classify the update scenario
 
 Pick ONE of three scenarios based on what you parsed in step 1:
@@ -206,5 +230,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
+- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/skills/apt-verify-proof/SKILL.md

@@ -89,8 +89,10 @@ For multi-model verification details:
 
 ## Config
 
-Settings in `.aperant/config.json` control behavior (run `/apt:setup` to configure):
-- `verification.evidence_capture` — capture screenshots + terminal output (default: true)
-- `verification.open_report` — open HTML in browser when done (default: true)
-- `multi_model.enabled` — run multi-model verification (default: false)
-- `multi_model.gemini.model` — Gemini preset: default/thorough/fast
+Settings live in the MERGED Aperant config (shared `.aperant/config.json` + per-device `.aperant/config.local.json`; local wins). Run `/apt:setup` to configure. Read via `apt-tools config read .` or the framework's `loadMergedProjectConfig()` — NEVER raw `JSON.parse(readFileSync('.aperant/config.json'))`, which misses per-device overrides.
+
+- `verification.evidence_capture` — shared. capture screenshots + terminal output (default: true)
+- `verification.open_report` — **per-device (config.local.json)** per AUDIT-001. open HTML in browser when done (default: true)
+- `multi_model.enabled` — shared. run multi-model verification (default: false)
+- `multi_model.cross_verification.tools` — **per-device (config.local.json)** per AUDIT-001. which CLIs to cross-verify with.
+- `multi_model.gemini.model` — shared. Gemini preset: default/thorough/fast

package/skills/apt-watch-ci/SKILL.md

@@ -87,7 +87,10 @@ For the `--tick` mode, execute exactly the following sequence — once — insid
 
 When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
 
-- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`. Else print the exact D-08 text:
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`.
+  - **DO NOT pass `--delete-branch`** to `gh pr merge` from this auto-merge path — ever, unconditionally. The watcher's cwd is the task worktree, where `gh`'s `--delete-branch` post-merge cleanup tries to `git switch <base>` and fails because `<base>` is checked out in the primary worktree. The remote merge has already succeeded by then; local branch + worktree cleanup is `/apt:close-task`'s job via `apt-tools task close-merged` → `computeWorktreeCleanup` (see FRAMEWORK-BUG-019).
+
+  Else print the exact D-08 text:
 
   ```
   ✅ CI green — merge in browser or run /apt:close-task post-merge

package/src/cli/ci-watch/stop-matrix.mjs

@@ -106,6 +106,23 @@ export function classify({ checks, state, prMetadata }) {
 		}
 	}
 
+	// 6b. BUG-031 defensive wait branch — if no checks are actually
+	// failing (everything is success / skipped / in_progress / neutral),
+	// never fall through to the default-red 'fix' at the bottom. Placed
+	// AFTER reviewer-pause so CHANGES_REQUESTED + no-failures still
+	// produces 'reviewer-pause' (locks existing semantics), BEFORE the
+	// remaining checks (identical-log, flake-skip, infra-backoff, fix)
+	// which all assume at least one failing row. Pre-fix, a PR with a
+	// success + a SKIPPED conditional CI job fell through to 'fix' and
+	// burned a fix attempt every tick on a non-existent failure.
+	if (failed.length === 0) {
+		return {
+			action: 'wait',
+			counts_toward_budget: false,
+			reason: 'no failing checks; awaiting in-flight or skipped',
+		}
+	}
+
 	// 7. Identical-log → non-converging fixer.
 	// Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
 	if (attempts > 0 && st.last_status && failed.length > 0) {

package/src/cli/commands/ci-watch.mjs

@@ -24,14 +24,36 @@
  * itself never shells out to gh.
  */
 
+import { spawnSync } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { acquireLock, releaseLock } from '../ci-watch/lock.mjs'
 import { deleteState, listWatches, readState, writeState } from '../ci-watch/state.mjs'
 import { classify, isFailing } from '../ci-watch/stop-matrix.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { requireMinVersion } from '../util/version-preflight.mjs'
+
+/**
+ * Installed kernel version — read once at module scope, same pattern as
+ * commands/check-version.mjs:108-109. Used by the version-preflight in
+ * `doTick` to fail loud (instead of infra-backoff-loop) when a future
+ * framework fix introduces a new tick flag and the user is on a stale
+ * install. See FRAMEWORK-BUG-017 rung 2 + the helper docstring for the
+ * "future-guard" framing.
+ */
+const INSTALLED_KERNEL_VERSION = (() => {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkgPath = resolve(here, '..', '..', '..', 'package.json')
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		return typeof pkg?.version === 'string' ? pkg.version : null
+	} catch {
+		return null
+	}
+})()
 
 const DEFAULT_TICK_INTERVAL_MS = 300_000 // 5 minutes
 const MAX_TICK_INTERVAL_MS = 30 * 60 * 1000 // 30 min
@@ -73,7 +95,7 @@ function validatePr(pr) {
  */
 export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 	if (!subcommand) {
-		return err('Usage: apt-tools ci-watch <start|stop|status|tick> <project-dir> [flags]')
+		return err('Usage: apt-tools ci-watch <start|stop|status|tick|sweep> <project-dir> [flags]')
 	}
 	if (!projectDir) {
 		return err(`Usage: apt-tools ci-watch ${subcommand} <project-dir> [flags]`)
@@ -91,9 +113,34 @@ export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 			return doStatus(root, flags)
 		case 'tick':
 			return doTick(root, flags)
+		case 'sweep':
+			return err(
+				'sweep is async; call cmdCiWatchSweep directly (the apt-tools dispatcher routes it separately)',
+			)
 		default:
-			return err(`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick`)
+			return err(
+				`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick, sweep`,
+			)
+	}
+}
+
+/**
+ * Async sibling for the `sweep` subcommand (the rate-limited orphaned-state
+ * walker). Split out from the sync `cmdCiWatch` dispatcher so the latter's
+ * return type stays `CommandResult` (not a `CommandResult | Promise` union)
+ * and the synchronous tests + callers don't need to be wrapped in `await`.
+ *
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ * @returns {Promise<CommandResult>}
+ */
+export async function cmdCiWatchSweep(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err('Usage: apt-tools ci-watch sweep <project-dir> [flags]')
 	}
+	const root = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	return await doSweep(root, flags)
 }
 
 // ---------------------------------------------------------------------------
@@ -119,12 +166,14 @@ function doStart(root, flags) {
 				command: 'ci-watch-start',
 				pr: Number(pr),
 				reason: 'already-armed',
+				scheduler_handle: existingState.scheduler_handle ?? null,
 				existing: {
 					task_id: existingState.task_id,
 					host: existingState.host,
 					attempts: existingState.attempts,
 					started_at: existingState.started_at,
 					deadline: existingState.deadline,
+					scheduler_handle: existingState.scheduler_handle ?? null,
 				},
 			},
 			2,
@@ -222,6 +271,91 @@ function doStop(root, flags) {
 	})
 }
 
+// ---------------------------------------------------------------------------
+// sweep — BUG-027 (c): manual GC for orphaned ci-watch state files.
+//
+// Enumerates all watcher state files via `listWatches(root)`, shells out
+// to `gh pr view --json state` for each one (rate-limited to ≤5/sec),
+// and removes the state files whose PR state is MERGED or CLOSED. Never
+// auto-runs on startup — opt-in manual subcommand only, per brief.
+// Honors APT_GH_FIXTURE_JSON for hermetic tests (returns the same body
+// for every PR — fine since the test fixtures we ship cover each
+// branch in isolation).
+// ---------------------------------------------------------------------------
+
+async function doSweep(root, flags) {
+	if (flags.get('orphaned') !== true) {
+		return err(
+			'ci-watch sweep currently supports only `--orphaned`. Usage: apt-tools ci-watch sweep <project-dir> --orphaned',
+		)
+	}
+	const dryRun = flags.get('dry-run') === true
+	const watches = listWatches(root)
+	const removed = []
+	const skipped = []
+	const ghFixture = process.env.APT_GH_FIXTURE_JSON
+	for (let i = 0; i < watches.length; i++) {
+		const watch = watches[i]
+		const pr = watch.pr
+		const prUrl = watch.pr_url ?? null
+		// Validate pr_url shape before passing to gh: must be an https:// URL
+		// or absent. An invalid value (e.g. a flag-injection string from a
+		// tampered state file) falls back to the integer pr number.
+		const safeUrl =
+			typeof prUrl === 'string' && /^https:\/\/.+/.test(prUrl) && !prUrl.startsWith('-')
+				? prUrl
+				: null
+		// Need a PR URL to call `gh pr view`; if absent, fall back to the
+		// integer pr arg which gh accepts for the active repo.
+		const target = safeUrl ?? String(pr)
+		let body = null
+		if (ghFixture) {
+			body = ghFixture
+		} else {
+			try {
+				const res = spawnSync('gh', ['pr', 'view', target, '--json', 'state'], {
+					cwd: root,
+					encoding: 'utf-8',
+				})
+				if (res.status === 0 && res.stdout) body = res.stdout
+			} catch {
+				/* gh transport error — skip this entry */
+			}
+		}
+		if (!body) {
+			skipped.push({ pr, reason: 'gh-unavailable' })
+			continue
+		}
+		let parsed
+		try {
+			parsed = JSON.parse(body)
+		} catch {
+			skipped.push({ pr, reason: 'malformed-gh-json' })
+			continue
+		}
+		const state = parsed?.state ?? null
+		if (state !== 'MERGED' && state !== 'CLOSED') {
+			skipped.push({ pr, reason: `pr-state-${state ?? 'unknown'}` })
+			continue
+		}
+		if (!dryRun) deleteState(root, pr)
+		removed.push({ pr, pr_state: state })
+		// Rate-limit ≤5/sec per brief — sleep 200ms between live gh calls.
+		// Use async setTimeout (non-blocking) rather than Atomics.wait.
+		if (!ghFixture && i < watches.length - 1) {
+			await new Promise((resolve) => setTimeout(resolve, 200))
+		}
+	}
+	return ok({
+		status: 'ok',
+		command: 'ci-watch-sweep',
+		dry_run: dryRun,
+		removed,
+		skipped,
+		total_watches: watches.length,
+	})
+}
+
 // ---------------------------------------------------------------------------
 // status
 // ---------------------------------------------------------------------------
@@ -261,6 +395,21 @@ function summarize(s) {
 // ---------------------------------------------------------------------------
 
 function doTick(root, flags) {
+	// FRAMEWORK-BUG-017 rung 2 (future-guard): emit a structured
+	// version_drift envelope when a future framework fix requires a
+	// new tick flag and the installed kernel predates it. The current
+	// pin to 0.6.7 (the version that introduced --payload-file) is a
+	// no-op on every 0.6.7+ install — but the scaffolding is in place
+	// for the NEXT new-flag fix to bump `introducedIn` without
+	// re-discovering the silent-infra-backoff failure mode.
+	const versionGate = requireMinVersion({
+		feature: 'payload-file',
+		introducedIn: '0.6.7',
+		installedVersion: INSTALLED_KERNEL_VERSION,
+		missingFlag: '--payload-file',
+	})
+	if (versionGate) return exitWith(versionGate, 1)
+
 	const prCheck = validatePr(flags.get('pr'))
 	if (typeof prCheck !== 'string') return prCheck
 	const pr = prCheck