agentwrangler 0.1.1-next.fbbbe7f → 0.1.1-next.fbffef0

package/README.md

@@ -1,184 +1,104 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="AgentWrangler logo" width="260">
+  <img src="https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/logo.png" alt="AgentWrangler logo" width="200">
 </p>
 
-<h1 align="center">AgentWrangler</h1>
+# AgentWrangler
 
-<p align="center">
-  <b>See where your Claude Code tokens go — and whether the work actually shipped.</b><br>
-  Local-first observability for Claude Code: token spend, session outcomes, waste detection,
-  and installable guardrails. Runs entirely on your machine.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/agentwrangler"><img src="https://img.shields.io/npm/v/agentwrangler" alt="npm version"></a>
-  <a href="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml"><img src="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://img.shields.io/node/v/agentwrangler"><img src="https://img.shields.io/node/v/agentwrangler" alt="node version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="license"></a>
-</p>
-
-![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
-
-<!--
-  All screenshots and the demo GIF in this README are captured from a SANITIZED instance
-  (Vite test-mode fixtures — anonymized names, no live data) so no real workspace/repository
-  names or paths are committed (SEC-101). Regenerate against `npx vite --mode test`.
--->
-
-## Why
-
-Claude Code tells you almost nothing about where your token budget goes. Sessions balloon,
-caches miss, background agents idle — and you find out when you hit the rate limit.
-AgentWrangler reads the transcripts Claude Code already writes to your disk and answers three
-questions:
-
-- **Where did the tokens go?** Per-model, per-workspace, per-session spend with cache economics.
-- **Did the work ship?** Sessions are linked to the pull requests they merged or closed.
-- **What should I change?** Ranked waste-source detectors with modeled savings — and one-click
-  guardrail hooks that warn *inside* Claude Code before waste happens.
-
-No cloud backend, no telemetry, no account. A daemon on `127.0.0.1`, a dashboard in your
-browser, and a SQLite file in your home directory.
+See where your Claude Code tokens go, inspect costly sessions, and track whether a change helped.
+AgentWrangler reads local Claude Code transcripts and serves a dashboard on your machine.
+No account or cloud backend is required.
 
 ## Quick start
 
+Requires **Node 22-24 and npm**, plus Claude Code transcripts for populated charts.
+
 ```sh
 npx agentwrangler@latest
 ```
 
-That's it — requires Node **22–24**. The daemon starts on `http://127.0.0.1:47821`, opens your
-browser, and scans your `~/.claude/projects` transcripts in the background; the dashboard
-appears immediately and fills in as the scan completes.
-
-More options (install from source, GitHub outcomes sync, environment variables):
-**[Getting started →](docs/getting-started.md)**
-
-## Features
-
-### Overview — verdict first, details on demand
-
-One screen answers "how bad is it this week": a spend verdict with trend, your top waste
-source with a copyable fix prompt, live rate-limit gauges (5-hour and 7-day), a burn forecast
-against your calibrated weekly limit, hot sessions, cache efficiency, and per-model
-context-per-turn tiles.
-
-![Overview tab — at-a-glance verdict, rate limits, burn forecast, hot sessions](docs/assets/overview.png)
-
-### Recommendations — waste-source detectors, ranked by impact
-
-Ten detector families watch your sessions for the patterns that actually burn tokens: cache
-misses (the biggest single lever), session hygiene, retry/redundant-read loops, tool-result
-bloat, model routing, idle background sessions, and more. Each recommendation shows modeled
-weekly savings, a confidence tier, and a concrete action — install a hook, copy a config
-snippet, or copy a guided prompt straight into Claude Code. Adopted changes flow into an
-**impact ledger** that tracks the measured effect, and modeled savings are never counted as
-achieved.
-
-![Recommendations tab — ranked detector families with modeled savings and one-click actions](docs/assets/recommendations.png)
-
-### Installable guardrails — local checks inside Claude Code, before the waste
-
-Five small hooks you can install from the dashboard (directly, or via a copyable prompt that
-Claude Code applies itself):
-
-| Guardrail | What it does |
-|---|---|
-| **Context-budget warning** | Warns when a session's context crosses your soft/hard thresholds |
-| **Loop guard** | Flags repeated identical tool failures before they spiral |
-| **Burn alert** | Catches idle sessions still burning tokens in the background |
-| **Pre-compaction checkpoint** | Copies the raw local transcript before an automatic compaction, subject to a local retention cap |
-| **Dangerous-command guard** | Asks before risky shell commands and denies a small catastrophe list |
-
-The context-budget and burn hooks warn. The loop guard warns before it denies repeated identical
-failures, and the dangerous-command guard can ask or deny. Direct install enables all five hooks;
-the copied install prompt enables the context-budget, loop, and burn hooks only. Thresholds are
-tunable from Settings, and direct uninstall removes every AgentWrangler hook.
-
-### Sessions — who spent it, and on what
-
-The highest-cost sessions ranked with their output-to-context split, model, friction band
-(API errors, tool failures, compactions, interrupts), and a "top X% by spend" self-percentile
-chip. Drill into any session for a turn-by-turn timeline, its cost drivers (which detectors
-fired and how hard), and a guided fix prompt built only from measured numbers.
-
-![Sessions tab — highest-cost sessions with friction bands and spend percentiles](docs/assets/sessions.png)
-
-<details>
-<summary>Session detail view</summary>
-
-![Session detail — per-session KPIs, cost drivers, and a measured-context fix prompt](docs/assets/session-detail.png)
-</details>
-
-### Workspaces — spend efficiency by repository
-
-Every repo you run Claude Code in, with spend share, trend, context-per-turn, cache-write
-share, Opus share, and $/turn. With a GitHub token configured, sessions are linked to the PRs
-and commits they produced — so you can see cost-per-merged-PR, not just cost.
-
-![Workspaces tab — per-repository spend, efficiency, and outcome linkage](docs/assets/workspaces.png)
-
-<details>
-<summary>Workspace detail view</summary>
-
-![Workspace detail — top sessions, context composition, and outcomes](docs/assets/workspace-detail.png)
-</details>
-
-### Weekly brief — one page, three decisions
-
-The week in one screen: spend verdict, what changed vs. last week, the top actions to take —
-with a **Copy as Markdown** button so the whole brief drops into a standup note or a message.
+Open **http://127.0.0.1:47821** if the browser does not open automatically. Keep the terminal
+running; press **Ctrl+C** to stop. The first scan runs in the background. An empty history is
+valid: use Claude Code, then return after ingestion. If a daemon is already running, stop it
+before starting another on the same port.
 
-![Briefs tab — weekly verdict, week-over-week deltas, and top actions](docs/assets/briefs.png)
+[Install from source, configure scan roots, or troubleshoot](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md).
 
-### Honest numbers, labeled as such
+## Your first five minutes
 
-Every metric carries an honesty-tier chip — `EXACT`, `LIST_EQUIV`, `MODELED`, `PROXY`,
-`DIRECTIONAL`, `EXPERIMENTAL` — so you always know what is measured versus estimated. Dollar
-figures are list-price *equivalents* (subscription plans aren't billed per token; tokens drive
-rate limits), and the built-in glossary ("How to read this dashboard") defines every
-key metric in plain language. The full tour: **[Dashboard tour →](docs/dashboard-tour.md)**
+1. **Check the scan.** In Overview, read the onboarding status. A completed scan with no
+   recommendations is a valid result. For an unexpected empty history, inspect scan roots
+   and parser health in Settings; saved scan-root changes require a daemon restart.
+2. **Find one expensive session.** Select a date window, open Workspaces, choose a workspace,
+   then open one of its sessions. Compare context, cache writes, and output before deciding
+   what to change.
+3. **Inspect one recommendation.** Open Recommendations and **Show details** on an instance.
+   Read its evidence and caveats. A modeled amount is a projection; directional advice may
+   have no dollar estimate. If nothing fires, there is nothing to adopt just to finish setup.
+4. **Make one deliberate change.** A copied prompt is an artifact to review and run yourself.
+   It does not edit files. After completing a supported change, use **I completed the change**
+   when offered, then **Track this change** to record a baseline.
+5. **Return to the Impact ledger.** Tracking starts observation, not a savings claim. Eligible
+   signals use a 14-day observation window and may finish inconclusive. You can finish this
+   first visit without a GitHub token, calibration, or installed hooks.
 
-## Privacy — local-only by design
+Dollar figures are **list-price equivalents**, not your subscription bill. Modeled savings
+are not achieved savings, and observed improvement does not prove the change caused it.
+GitHub linkage adds outcome metadata; calibration enables the burn forecast. Local spend,
+session inspection, and supported recommendation tracking work without either.
 
-- The daemon binds to **`127.0.0.1`** only. There is no cloud backend, telemetry, or account.
-- Most dashboard data is **aggregates, ids, counts, and structural anchors**. Local command text
-  and filesystem paths can also be retained in SQLite; treat the database as sensitive. The optional
-  direct-install PreCompact hook can separately copy full raw transcripts locally.
-- The optional GitHub token is read locally, never logged, never persisted to the DB.
-- Usage refreshes can call Anthropic with an existing Claude Code sign-in. GitHub outcomes sync
-  calls GitHub only when a token is configured; calibration and G2 judging are separate opt-ins.
+[Worked example: trim always-loaded context and inspect its effect](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context).
 
-Full details, including exactly what is and isn't stored: **[Privacy model →](docs/privacy.md)**
+## Dashboard preview
 
-## Configuration
+![Synthetic Overview: spend for the selected window, model mix, and links to sessions and recommendations](https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/overview.png)
 
-Everything is optional with sensible defaults — port, DB path, scan roots, GitHub token, and
-more are environment variables documented in [Getting started](docs/getting-started.md#configuration)
-and [`.env.example`](.env.example).
+This static preview uses synthetic data. [The dashboard tour](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md)
+contains the other views and an optional animated preview.
 
-## Documentation
+## Pick a question
 
-| Page | What's in it |
+| I want to... | Start here |
 |---|---|
-| [Getting started](docs/getting-started.md) | Install paths, optional setup, configuration, troubleshooting |
-| [Dashboard tour](docs/dashboard-tour.md) | Every tab in depth, plus the metric vocabulary |
-| [Privacy model](docs/privacy.md) | Local storage, raw-checkpoint exception, and network integrations |
-| [Architecture](docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) | Daemon, ingestion, detector, and query design |
-| [Data model & metrics](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) | SQLite schema and metric definitions |
-| [Contributing](.github/CONTRIBUTING.md) | Dev setup, checks, PR expectations |
-| [Security policy](.github/SECURITY.md) | Threat model and how to report a vulnerability |
-
-## Limitations
-
-- Reads Claude Code's JSONL transcript format; an upstream format change can require an
-  ingestion update.
-- Tested on Windows; macOS/Linux are believed working — reports welcome.
-- Single local user by design — no multi-user or team-aggregation mode.
-- Outcome linkage needs a read-only GitHub token; without one the feature stays inert (and
-  Settings says so — nothing fails silently).
-
-## License
-
-[Apache 2.0](LICENSE) © 2026 AgentWrangler contributors.
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md), [SECURITY.md](.github/SECURITY.md), and
-[CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).
+| Find where my tokens went | [Workspaces and Sessions](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#workspaces) |
+| Turn a recommendation into a change | [Worked example](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context) |
+| Understand the dollars and verdicts | [Metric vocabulary](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#glossary-how-to-read-this-dashboard) |
+| Fix an empty dashboard | [First launch](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#first-launch) |
+| Connect GitHub or calibrate limits | [Optional setup](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#optional-setup) |
+| Read a weekly summary | [Briefs](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#briefs) |
+
+## Installable guardrails — local checks inside Claude Code, before the waste
+
+Hooks are optional and require an explicit install. Settings **Install directly** installs
+five hooks; **Copy install prompt** prepares instructions for three. Copying alone installs nothing.
+
+| Hook | Behavior | Install path |
+|---|---|---|
+| Context-budget | Warns when context crosses configured thresholds | Direct or copied prompt |
+| Loop guard | Warns, then can deny repeated identical failures | Direct or copied prompt |
+| Burn alert | Warns about session budget consumption | Direct or copied prompt |
+| Dangerous-command | Can ask or deny risky commands | Direct only |
+| PreCompact checkpoint | Copies raw transcripts locally, with retention limits | Direct only |
+
+[Installation, removal, and the checkpoint privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#in-session-guardrails).
+
+## Privacy and limits
+
+- The daemon binds to **127.0.0.1**. There is no telemetry or hosted product backend.
+- SQLite contains aggregates and structural data, and can also contain local command text
+  and filesystem paths. Treat it as sensitive. The optional PreCompact hook makes separate
+  raw transcript copies on your machine.
+- Usage refresh can contact Anthropic using your existing Claude Code sign-in. GitHub
+  outcomes sync requires a configured token. [Privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/privacy.md).
+- Claude Code format changes can require parser updates. This is a single-user tool.
+- Windows local validation and Linux/macOS CI smoke coverage do not establish full native
+  accessibility or credential-store compatibility on every platform.
+
+## Deeper documentation
+
+[Configuration](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#configuration) |
+[Architecture](https://github.com/Doogit/AgentWrangler/blob/main/docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) |
+[Data model and metrics](https://github.com/Doogit/AgentWrangler/blob/main/docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) |
+[Contributing](https://github.com/Doogit/AgentWrangler/blob/main/.github/CONTRIBUTING.md) |
+[Security policy](https://github.com/Doogit/AgentWrangler/blob/main/.github/SECURITY.md)
+
+[Apache 2.0](https://github.com/Doogit/AgentWrangler/blob/main/LICENSE).

package/dist/apply/jobs.js

@@ -200,6 +200,7 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
     const changedPaths = [];
     let finalized = false;
     let fatalExitMessage = null;
+    let killTimer;
     const cleanup = () => {
         fs.unlink(settingsPath, () => { });
     };
@@ -251,9 +252,11 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
         }
     });
     const timer = setTimeout(() => {
+        // Keep the job exclusive until the child has actually closed. Publishing
+        // FAILED here lets a retry (or workspace cleanup) race the dying process.
+        fatalExitMessage ??= "job timed out";
         proc.kill("SIGTERM");
-        setTimeout(() => proc.kill("SIGKILL"), 2000);
-        markFailed("job timed out");
+        killTimer = setTimeout(() => proc.kill("SIGKILL"), 2000);
     }, rt.timeoutMs);
     proc.on("error", (err) => {
         clearTimeout(timer);
@@ -261,6 +264,7 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
     });
     proc.on("close", (code) => {
         clearTimeout(timer);
+        clearTimeout(killTimer);
         if (finalized)
             return;
         finalized = true;
@@ -298,7 +302,10 @@ function completeApplyPhase(db, job, rec, result, rt) {
     let runId = null;
     const completedAt = rt.now();
     try {
-        adoptRecommendation(job.rec_id, completedAt.getTime());
+        adoptRecommendation(job.rec_id, completedAt.getTime(), {
+            machineConfirmed: true,
+            actionRevision: job.job_id,
+        });
         runId = randomUUID();
         const evidencePackHash = createHash("sha256")
             .update(JSON.stringify(rec.evidence))
@@ -413,6 +420,9 @@ export function rollbackApplyJob(jobId) {
     if (row.status !== "APPLIED" && row.status !== "CONFIRMING") {
         throw new Error("job cannot be rolled back from this state");
     }
+    if (db.prepare("SELECT 1 FROM effect_cycles WHERE rec_id=? LIMIT 1").get(row.rec_id)) {
+        throw new Error("Whole-file backup rollback is not a supported effect inverse. Revert manually and attest the rollback in the effect ledger.");
+    }
     if (row.backup_path === null)
         throw new Error("no backup available");
     fs.copyFileSync(row.backup_path, row.file_ref);

package/dist/daemon/effect-pass.js

@@ -0,0 +1,24 @@
+import { runMeasurementPass } from "../detector/measurement.js";
+import { ESF_EFFECT_WRITER_ENABLED } from "../effects/gate.js";
+import { effectEngineForDb } from "../query/api/effect-service.js";
+const INTERVAL_MS = 60 * 60 * 1000;
+const lastPass = new WeakMap();
+/** Probe-clock scheduling; restarting can safely replay the bounded, idempotent engine pass. */
+export function runEffectMeasurementPass(db, now) {
+    if (!ESF_EFFECT_WRITER_ENABLED) {
+        runMeasurementPass(db, now);
+        return;
+    }
+    const previous = lastPass.get(db);
+    const current = now.getTime();
+    if (previous !== undefined && current >= previous && current - previous < INTERVAL_MS)
+        return;
+    lastPass.set(db, current);
+    try {
+        effectEngineForDb(db).runPass(now);
+    }
+    catch {
+        // Never expose source identities or DB contents in a background error.
+        console.warn("Effect measurement pass failed; retrying on the next scheduled pass.");
+    }
+}

package/dist/daemon/http.js

@@ -138,6 +138,16 @@ function requiresSessionToken(pathname) {
         return true;
     if (/^\/api\/recommendations\/jobs\/[^/]+\/(confirm|rollback)$/.test(pathname))
         return true;
+    if (/^\/api\/esf\/effects\/(track|stop|close|rollback|attest-rollback)$/.test(pathname))
+        return true;
+    if (pathname === "/api/work-records" || pathname === "/api/work-records/ids")
+        return true;
+    if (/^\/api\/work-records\/[^/]+\/(edit|closeout|archive|reopen|sessions|contexts|delete)$/.test(pathname))
+        return true;
+    if (/^\/api\/work-records\/[^/]+\/(sessions|contexts)\/[^/]+\/detach$/.test(pathname))
+        return true;
+    if (pathname === "/api/work-records/allocations/recompute")
+        return true;
     return false;
 }
 /**

package/dist/daemon/index.js

@@ -22,7 +22,6 @@ import { openDb } from "../db/open.js";
 import { configGet as bptConfigGet, calibrateBytesPerToken } from "../detector/calibration.js";
 import { runContextProbe } from "../detector/context-probe.js";
 import { runDetectors } from "../detector/index.js";
-import { runMeasurementPass } from "../detector/measurement.js";
 import { installHook, uninstallHook } from "../hook/install.js";
 import { collectSessionChurn } from "../ingest/churn-collector.js";
 import { runPostProbeHook, setPostIngestHook, setPostProbeHook } from "../ingest/detector-hook.js";
@@ -37,7 +36,9 @@ import { generateWeeklyReport } from "../query/api/reports.js";
 import { setQueryDb } from "../query/db-context.js";
 import { getSettingsData, setHealthInstance, setRuntimeResetHook, } from "../query/settings-store.js";
 import { loadConfig } from "./config.js";
+import { runEffectMeasurementPass } from "./effect-pass.js";
 import { createServer } from "./http.js";
+import { createDaemonLifecycle } from "./lifecycle.js";
 import { createOutcomesPassRunner } from "./outcomes-pass.js";
 import { setReady, setScanRoots, setScanState } from "./readiness.js";
 const VERSION = "0.1.0";
@@ -107,6 +108,10 @@ if (isSmoke) {
         "review_findings",
         "recommendations",
         "recommendation_effects",
+        "effect_cycles",
+        "effect_guardrail_results",
+        "effect_rollback_operations",
+        "effect_mutation_keys",
         "apply_jobs",
         "analysis_runs",
         "ingest_quarantine",
@@ -150,18 +155,16 @@ function runProbePass(label) {
         const now = new Date();
         const { rows } = runContextProbe(db, now);
         console.log(`ContextProbe[${label}]: ${rows} row(s) upserted`);
-        // W4: measurement pass after each probe (best-effort; the seam never throws
-        // through, and runMeasurementPass itself is guarded/log-not-throw).
+        // Best-effort measurement after each probe, using the same observation clock.
         runPostProbeHook(db, now);
     }
     catch (e) {
         console.log(`ContextProbe[${label}]: skipped — ${e instanceof Error ? e.message : String(e)}`);
     }
 }
-// Wire the W4 Impact Ledger measurement pass onto the post-probe seam. The pass
-// receives the probe's clock (deterministic; NFR-107), is throttled internally.
+// Versioned measurement owns new cycles; W4 history stays read-only under the code gate.
 setPostProbeHook((probeDb, now) => {
-    runMeasurementPass(probeDb, now);
+    runEffectMeasurementPass(probeDb, now);
 });
 runProbePass("boot");
 // ── Outcomes bootstrap (WP5 — best-effort, never crash daemon) ────────────────
@@ -169,10 +172,6 @@ runProbePass("boot");
 // The runner (src/daemon/outcomes-pass.ts) adds a hard 15-min per-pass deadline:
 // a hung pass can no longer wedge the poll cadence forever — the running flag
 // always clears and the next poll resumes.
-let outcomesTimer = null;
-let reportsTimer = null;
-let reportsRunning = false;
-let bptCalibrationTimer = null;
 const outcomesRunner = createOutcomesPassRunner({
     db,
     probe: () => runProbePass("poll"),
@@ -186,29 +185,31 @@ const outcomesRunner = createOutcomesPassRunner({
 function runOutcomesPass() {
     return outcomesRunner.run();
 }
+// R12 bytes→token calibration — best-effort, never crash the daemon.
+// Runs on boot (deferred) and weekly when: opt-in enabled AND ratio is absent
+// or older than 30 days. Mirrors the outcomes bootstrap pattern.
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+function runBptCalibrationIfStale() {
+    const enabled = bptConfigGet(db, "bytes_per_token_calibration_enabled");
+    if (enabled !== "true")
+        return;
+    const measuredAt = bptConfigGet(db, "bytes_per_token_measured_at");
+    if (measuredAt !== null && Date.now() - new Date(measuredAt).getTime() < THIRTY_DAYS_MS)
+        return;
+    calibrateBytesPerToken(db).catch((e) => {
+        console.error(`Bytes-per-token calibration failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
+    });
+}
 // ── Deferred boot scan (runs AFTER the HTTP port is bound) ───────────────────
 // startTailBatched() performs a yielding initial back-scan (ingestAllKnown +
 // reconcile), then arms the tail/discovery timers. We do NOT
 // also call runBackscan — that would spin up a second Ingestor whose separate
 // Health instance is the one surfaced in Settings. One Ingestor, one Health.
 // Bounded: if ingestion fails to start, still serve the dashboard (degraded).
-let handle = null;
-// One-shot guard: runBootScan executes exactly once regardless of how many
-// requests or timers fire kickBootScan concurrently.
-let scanKicked = false;
-function kickBootScan() {
-    if (scanKicked)
-        return;
-    scanKicked = true;
-    // Use setImmediate so the triggering HTTP response flushes before boot work
-    // starts. The scan itself also yields between bounded batches.
-    setImmediate(() => {
-        runBootScan().catch((e) => {
-            console.error(`Boot scan failed: ${e instanceof Error ? e.message : String(e)}`);
-        });
-    });
-}
+// The one-shot kick guard, the daemon-owned intervals, and shutdown ordering
+// live in the lifecycle harness (src/daemon/lifecycle.ts).
 async function runBootScan() {
+    let handle = null;
     try {
         const scanRoots = getSettingsData(db).scan_roots;
         setScanRoots(scanRoots);
@@ -261,21 +262,8 @@ async function runBootScan() {
             console.error(`Self-churn collection failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
         }
     });
-    // R12 bytes→token calibration — best-effort, never crash the daemon.
-    // Runs on boot (deferred) and weekly when: opt-in enabled AND ratio is absent
-    // or older than 30 days. Mirrors the outcomes bootstrap pattern.
-    const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
-    function runBptCalibrationIfStale() {
-        const enabled = bptConfigGet(db, "bytes_per_token_calibration_enabled");
-        if (enabled !== "true")
-            return;
-        const measuredAt = bptConfigGet(db, "bytes_per_token_measured_at");
-        if (measuredAt !== null && Date.now() - new Date(measuredAt).getTime() < THIRTY_DAYS_MS)
-            return;
-        calibrateBytesPerToken(db).catch((e) => {
-            console.error(`Bytes-per-token calibration failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
-        });
-    }
+    // Deferred boot calibration check (the weekly interval is armed by the
+    // lifecycle harness after this scan resolves).
     setImmediate(() => {
         try {
             runBptCalibrationIfStale();
@@ -284,42 +272,31 @@ async function runBootScan() {
             console.error(`Bytes-per-token calibration boot failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
         }
     });
-    bptCalibrationTimer = setInterval(() => {
-        try {
-            runBptCalibrationIfStale();
-        }
-        catch (e) {
-            console.error(`Bytes-per-token calibration poll failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
-        }
-    }, 7 * 24 * 60 * 60 * 1000);
-    // 10-minute poll — guarded by outcomesRunning to prevent overlap
-    outcomesTimer = setInterval(() => {
+    return handle;
+}
+// ── Lifecycle harness: boot-kick guard, daemon intervals, shutdown ordering ──
+// closeServer closes over `server` (declared below); shutdown only ever runs
+// after listen, so the reference is initialized by then.
+const lifecycle = createDaemonLifecycle({
+    bootScan: runBootScan,
+    calibrationTick: runBptCalibrationIfStale,
+    outcomesTick: () => {
         runOutcomesPass().catch((e) => {
             console.error(`Outcomes poll failed: ${e instanceof Error ? e.message : String(e)}`);
         });
-    }, 10 * 60 * 1000);
-    reportsTimer = setInterval(async () => {
-        if (reportsRunning)
-            return;
-        reportsRunning = true;
-        try {
-            await Promise.resolve(generateWeeklyReport(db, new Date()));
-        }
-        catch (e) {
-            console.error(`Weekly report poll failed: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        finally {
-            reportsRunning = false;
-        }
-    }, 7 * 24 * 60 * 60 * 1000);
-}
+    },
+    reportsTick: () => generateWeeklyReport(db, new Date()),
+    closeServer: (onClosed) => server.close(onClosed),
+    closeDb: () => db.close(),
+    onClosed: () => process.exit(0),
+});
 // ── 4. Start HTTP server ──────────────────────────────────────────────────────
 // Bind the port BEFORE the back-scan so the loading page is delivered
 // immediately while the initial scan yields between file batches.
 // Generate a random in-memory session token for the CSRF token gate.
 // NEVER log it, NEVER persist it — it lives only in process memory.
 const sessionToken = randomUUID();
-const server = createServer(db, config.port, config.uiRoot, sessionToken, kickBootScan);
+const server = createServer(db, config.port, config.uiRoot, sessionToken, lifecycle.kickBootScan);
 server.listen(config.port, "127.0.0.1", () => {
     const url = `http://127.0.0.1:${config.port}`;
     console.log(`Listening on ${url}`);
@@ -332,7 +309,7 @@ server.listen(config.port, "127.0.0.1", () => {
     // Fallback: kick the back-scan after 3 s even if no browser request arrives
     // (headless mode, --no-open, CI). The one-shot guard in kickBootScan() makes
     // whichever trigger fires first the only one that runs the scan.
-    setTimeout(kickBootScan, 3000);
+    lifecycle.armBootFallback();
 });
 /** Open `url` in the system default browser (best-effort; never crashes the daemon). */
 function openBrowser(url) {
@@ -355,24 +332,8 @@ function openBrowser(url) {
 // ── Graceful shutdown ─────────────────────────────────────────────────────────
 process.on("SIGINT", () => {
     console.log("Shutting down…");
-    handle?.stop();
-    if (outcomesTimer !== null)
-        clearInterval(outcomesTimer);
-    if (reportsTimer !== null)
-        clearInterval(reportsTimer);
-    server.close(() => {
-        db.close();
-        process.exit(0);
-    });
+    lifecycle.shutdown();
 });
 process.on("SIGTERM", () => {
-    handle?.stop();
-    if (outcomesTimer !== null)
-        clearInterval(outcomesTimer);
-    if (reportsTimer !== null)
-        clearInterval(reportsTimer);
-    server.close(() => {
-        db.close();
-        process.exit(0);
-    });
+    lifecycle.shutdown();
 });