@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/metrics.d.ts

@@ -156,6 +156,25 @@ export interface PrePassFallbackBucket {
     actualBackend: string;
     count: number;
 }
+/**
+ * docs/design/appendices/fetch-window-cost-reduction.md §10.1 — per-backend per-attempt
+ * histogram used to verify Phase 1.5 (CLI instruction-file
+ * minimization). The Claude `cacheCreationTokensPerAttempt` histogram is
+ * the load-bearing surface on Claude; on Codex / Gemini / OpenCode the
+ * provider exposes no paid cache-creation dimension, so the per-session
+ * input-token spend is the equivalent verification signal — every byte
+ * of the instruction file is billed at the full input rate.
+ *
+ * `actualBackend` is the resolved backend that produced the attempt's
+ * row (matches `agent_actions.backend`). Attempts whose backend is
+ * unknown (NULL column on legacy rows) are dropped from the histogram
+ * rather than bucketed under `unknown` — without a backend axis the
+ * row cannot prove the Phase 1.5 saving and would dilute every bucket.
+ */
+export interface PrePassPerBackendBucket {
+    actualBackend: string;
+    histogram: HistogramSummary;
+}
 export interface PrePassMetricsSnapshot {
     /** Window in days the snapshot covers. */
     windowDays: number;
@@ -175,6 +194,55 @@ export interface PrePassMetricsSnapshot {
     durationMsByIntegration: PrePassDurationBucket[];
     /** Per-(routine, requestedBackend, actualBackend) fallback count. */
     fallbacks: PrePassFallbackBucket[];
+    /**
+     * docs/design/appendices/fetch-window-cost-reduction.md §10.1 — per-attempt histogram
+     * of `cache_creation_tokens`. The Phase 1 success criterion is
+     * `p50` dropping by ≥25 K (from ~89 K baseline) across all
+     * `routine.fetch_window` attempts in the window. Snapshot-level
+     * (not per-routine / per-integration) because the cache_create cost
+     * is dominated by what the SDK loads at session start, which is
+     * identical across parents — splitting per-routine would just
+     * fragment the same population without adding a signal.
+     *
+     * Phase 1.5 amendment: filtered to `actualBackend === 'claude'` only.
+     * Codex / Gemini parsers hard-code `cache_creation_tokens = 0` (their
+     * providers don't expose a paid cache-creation dimension), and
+     * including those zeros would skew p50 toward 0 and obscure the
+     * Phase 1 verification target. Post-D13, when the OpenCode core
+     * starts populating cache.write into the same column, extend the
+     * filter to `IN ('claude', 'opencode')`.
+     */
+    cacheCreationTokensPerAttempt: HistogramSummary;
+    /**
+     * Companion to `cacheCreationTokensPerAttempt`: per-attempt histogram
+     * of `cache_read_tokens`. Together with `cacheCreationTokensPerAttempt`
+     * the operator can derive the cache reuse ratio (`p50(read) /
+     * p50(create)`) directly from the snapshot — the design's §1.1 table
+     * compared the Haiku reuse ratio (1.51×) to Sonnet's (8.05×) as the
+     * primary symptom of the cost shape, and Phase 1 should leave the
+     * read side unchanged while shrinking the create side.
+     *
+     * Same Phase 1.5 filter as `cacheCreationTokensPerAttempt` —
+     * Claude-only — for symmetry, so the reuse ratio derived from the
+     * two histograms always reflects the same population.
+     */
+    cacheReadTokensPerAttempt: HistogramSummary;
+    /**
+     * docs/design/appendices/fetch-window-cost-reduction.md §10.1 (Phase 1.5) — per-backend
+     * histogram of `tokens_input` for `routine.fetch_window` attempts. The
+     * non-Claude analog of `cacheCreationTokensPerAttempt`: this is the
+     * surface that directly observes Phase 1.5's CLI instruction-file
+     * minimization on Codex / Gemini (and OpenCode, post-D13).
+     */
+    inputTokensByBackend: PrePassPerBackendBucket[];
+    /**
+     * docs/design/appendices/fetch-window-cost-reduction.md §10.1 (Phase 1.5) — per-backend
+     * histogram of `cost_usd` for `routine.fetch_window` attempts.
+     * Surfaces the dollar impact of Phase 1.5 / Phase 3 on each backend
+     * independently — provider pricing differs significantly, so a single
+     * cross-backend cost number would not be actionable.
+     */
+    costUsdByBackend: PrePassPerBackendBucket[];
 }
 /**
  * Per-`mt_id` consecutive-failure gauge bucket. Tracks the
@@ -328,7 +396,7 @@ export declare class MetricsCollector {
      */
     collectDelegatedTaskMetrics(days?: number): DelegatedTaskMetricsSnapshot;
     /**
-     * PRE_PASS_FAN_OUT_DESIGN.md §7.3 — pre-pass fan-out metrics.
+     * docs/design/appendices/pre-pass-fan-out.md §7.3 — pre-pass fan-out metrics.
      *
      * Aggregates `routine.fetch_window` audit rows (one per attempt per
      * integration per parent routine) into the four metric families
@@ -450,6 +518,25 @@ interface PrePassParsedAttempt {
     fallbackTriggered: boolean;
     requestedBackend: string | null;
     actualBackend: string | null;
+    /**
+     * Per-attempt SDK-reported `cache_creation_tokens`. May be `null` for
+     * legacy rows written before the column was populated, or for non-Claude
+     * backends that don't surface a cache-create signal — those rows are
+     * dropped from the histogram so the snapshot reflects only attempts
+     * where the metric is meaningful (Phase 1's target).
+     */
+    cacheCreationTokens: number | null;
+    /** Per-attempt SDK-reported `cache_read_tokens`; same nullability rules. */
+    cacheReadTokens: number | null;
+    /**
+     * Per-attempt `tokens_input` from `agent_actions.tokens_input`.
+     * Surfaces as the per-backend `inputTokensByBackend` histogram — the
+     * non-Claude analog of `cacheCreationTokensPerAttempt` since Codex /
+     * Gemini providers don't expose a paid cache-creation dimension.
+     * `null` rows are dropped from the histogram for the same reason as
+     * the cache columns.
+     */
+    tokensInput: number | null;
 }
 /**
  * Pure aggregation kernel for `collectPrePassMetrics`. Takes the parsed
@@ -462,4 +549,3 @@ interface PrePassParsedAttempt {
  */
 export declare function aggregatePrePassMetrics(attempts: readonly PrePassParsedAttempt[], windowDays: number, collectedAt: string): PrePassMetricsSnapshot;
 export {};
-//# sourceMappingURL=metrics.d.ts.map

package/dist/core/metrics.js

@@ -241,7 +241,7 @@ export class MetricsCollector {
         };
     }
     /**
-     * PRE_PASS_FAN_OUT_DESIGN.md §7.3 — pre-pass fan-out metrics.
+     * docs/design/appendices/pre-pass-fan-out.md §7.3 — pre-pass fan-out metrics.
      *
      * Aggregates `routine.fetch_window` audit rows (one per attempt per
      * integration per parent routine) into the four metric families
@@ -275,7 +275,8 @@ export class MetricsCollector {
         let rows = [];
         try {
             rows = this.db
-                .prepare(`SELECT cost_usd, duration_ms, backend, detail
+                .prepare(`SELECT cost_usd, duration_ms, backend, detail,
+                  tokens_input, cache_creation_tokens, cache_read_tokens
              FROM agent_actions
             WHERE action_type = 'routine.fetch_window'
               AND started_at > datetime('now', '-' || ? || ' days')
@@ -320,6 +321,9 @@ export class MetricsCollector {
                 fallbackTriggered: pp.fallbackTriggered === true,
                 requestedBackend: typeof pp.requestedBackend === "string" ? pp.requestedBackend : null,
                 actualBackend: row.backend,
+                tokensInput: row.tokens_input,
+                cacheCreationTokens: row.cache_creation_tokens,
+                cacheReadTokens: row.cache_read_tokens,
             });
         }
         return aggregatePrePassMetrics(attempts, window, collectedAt);
@@ -829,6 +833,16 @@ export function aggregateManagedTaskRuns(rows) {
     return totals;
 }
 function emptyPrePassSnapshot(windowDays, collectedAt) {
+    const emptyHistogram = {
+        count: 0,
+        sum: 0,
+        min: null,
+        max: null,
+        avg: null,
+        p50: null,
+        p90: null,
+        p95: null,
+    };
     return {
         windowDays,
         collectedAt,
@@ -839,6 +853,10 @@ function emptyPrePassSnapshot(windowDays, collectedAt) {
         costUsdByRoutine: [],
         durationMsByIntegration: [],
         fallbacks: [],
+        cacheCreationTokensPerAttempt: emptyHistogram,
+        cacheReadTokensPerAttempt: emptyHistogram,
+        inputTokensByBackend: [],
+        costUsdByBackend: [],
     };
 }
 /**
@@ -987,6 +1005,60 @@ export function aggregatePrePassMetrics(attempts, windowDays, collectedAt) {
     fallbacks.sort((a, b) => a.routine.localeCompare(b.routine)
         || a.requestedBackend.localeCompare(b.requestedBackend)
         || a.actualBackend.localeCompare(b.actualBackend));
+    // Cache-creation / cache-read token histograms — design §10.1 surface
+    // for verifying Phase 1 cost reduction. Phase 1.5 amendment: restrict
+    // to `actualBackend === 'claude'`. Codex / Gemini parsers persist
+    // `cache_creation_tokens = 0` (their providers don't expose a paid
+    // cache-creation dimension); including those zeros would skew p50
+    // downward and obscure the Phase 1 verification target. Post-D13, when
+    // the OpenCode core starts populating `cache.write` into the same
+    // column, widen the predicate to also accept `'opencode'`.
+    const cacheCreationSamples = [];
+    const cacheReadSamples = [];
+    // Phase 1.5 — per-backend `tokens_input` + `cost_usd` histograms. The
+    // non-Claude analog of the cache-create metric: every byte of the
+    // instruction file is billed at the full input rate on Codex / Gemini /
+    // OpenCode, so input-tokens directly observe Phase 1.5's reduction.
+    const inputTokensByBackend = new Map();
+    const costUsdByBackend = new Map();
+    for (const att of attempts) {
+        if (att.actualBackend === "claude") {
+            if (typeof att.cacheCreationTokens === "number") {
+                cacheCreationSamples.push(att.cacheCreationTokens);
+            }
+            if (typeof att.cacheReadTokens === "number") {
+                cacheReadSamples.push(att.cacheReadTokens);
+            }
+        }
+        if (att.actualBackend === null)
+            continue;
+        if (typeof att.tokensInput === "number") {
+            const samples = inputTokensByBackend.get(att.actualBackend);
+            if (samples)
+                samples.push(att.tokensInput);
+            else
+                inputTokensByBackend.set(att.actualBackend, [att.tokensInput]);
+        }
+        // `costUsd` is always a number on the parsed row (NULL coalesces to
+        // 0 in the projection above). Zero-cost attempts are still
+        // information — they signal cost-source = sdk failed to populate or
+        // a session that exited before billing — keep them in the bucket.
+        const costSamples = costUsdByBackend.get(att.actualBackend);
+        if (costSamples)
+            costSamples.push(att.costUsd);
+        else
+            costUsdByBackend.set(att.actualBackend, [att.costUsd]);
+    }
+    const inputTokensByBackendBuckets = [];
+    for (const [actualBackend, samples] of inputTokensByBackend.entries()) {
+        inputTokensByBackendBuckets.push({ actualBackend, histogram: summarize(samples) });
+    }
+    inputTokensByBackendBuckets.sort((a, b) => a.actualBackend.localeCompare(b.actualBackend));
+    const costUsdByBackendBuckets = [];
+    for (const [actualBackend, samples] of costUsdByBackend.entries()) {
+        costUsdByBackendBuckets.push({ actualBackend, histogram: summarize(samples) });
+    }
+    costUsdByBackendBuckets.sort((a, b) => a.actualBackend.localeCompare(b.actualBackend));
     return {
         windowDays,
         collectedAt,
@@ -997,6 +1069,9 @@ export function aggregatePrePassMetrics(attempts, windowDays, collectedAt) {
         costUsdByRoutine,
         durationMsByIntegration,
         fallbacks,
+        cacheCreationTokensPerAttempt: summarize(cacheCreationSamples),
+        cacheReadTokensPerAttempt: summarize(cacheReadSamples),
+        inputTokensByBackend: inputTokensByBackendBuckets,
+        costUsdByBackend: costUsdByBackendBuckets,
     };
 }
-//# sourceMappingURL=metrics.js.map

package/dist/core/migration-backup.d.ts

@@ -215,4 +215,3 @@ export declare function stashOverwrittenTargetEntries(targetDir: string, entries
  * collisions too) then re-places the original target-side version.
  */
 export declare function restoreOverwrittenTargetEntries(backup: BackupResult, targetDir: string, entries: string[]): void;
-//# sourceMappingURL=migration-backup.d.ts.map

package/dist/core/migration-backup.js

@@ -331,6 +331,7 @@ export function inspectDir(rootDir) {
  * user data that happens to share the name.
  */
 export const AGENT_FILE_TOP_LEVEL = new Set([
+    // Loose top-level survivors (legacy + canonical _index.md).
     "today.md",
     "yesterday.md",
     "roadmap.md",
@@ -338,6 +339,9 @@ export const AGENT_FILE_TOP_LEVEL = new Set([
     "context-index.md",
     "agent-journal.md",
     "user.md",
+    // Legacy top-level dirs (pre-CONTEXT_VAULT_REDESIGN) — kept so an
+    // upgrading install whose target carries them is not flagged
+    // foreign.
     "agent",
     "bases",
     "daily",
@@ -353,6 +357,13 @@ export const AGENT_FILE_TOP_LEVEL = new Set([
     "user",
     "user-details",
     "weekly",
+    // CONTEXT_VAULT_REDESIGN six-class top-level dirs.
+    "identity",
+    "state",
+    "plans",
+    "journal",
+    "knowledge",
+    "policies",
 ]);
 /**
  * Entries the migration silently ignores in a target directory — either
@@ -931,4 +942,3 @@ function restoreDirectory(srcDir, dstDir) {
         }
     }
 }
-//# sourceMappingURL=migration-backup.js.map

package/dist/core/morning/agent-journal-appender.d.ts

@@ -0,0 +1,264 @@
+/**
+ * `appendMorningRoutineJournalEntry` — assemble the one-block English
+ * audit-trail entry for `journal/agent.md` from **structured sources
+ * only** (agent_actions rows + daily/<yesterday>.md frontmatter
+ * deterministic fs read) and append it to the journal file.
+ *
+ * Spec: `docs/design/appendices/morning-routine-optimization.md`
+ * §"Daemon-side modules to add" → agent-journal-appender (⑥). Phase 2
+ * ships this module unwired; the orchestrator wires it after both
+ * stages finish and before the parent audit row is emitted.
+ *
+ * Output shape (matches today's Step 9 byte-for-byte so `pnpm audit`
+ * keeps parsing it):
+ *
+ *     ## 2026-05-15 morning routine
+ *     - Day-type: weekday
+ *     - Journal: daily/2026-05-14.md (42 lines, 3 projects referenced)
+ *     - Inbox: 4 files triaged, 4 moved to scratch, 1 DM-confirmations sent
+ *     - Checks from routines/morning.md: (none)
+ *     - Anomalies / skipped steps: (none)
+ *
+ * The `- Journal: ...` line is replaced by a `Journal synthesis: ...`
+ * variant when the daily file is absent or Stage B did not succeed:
+ *
+ *     - Journal synthesis: skipped (no prior-day data)               (first-run)
+ *     - Journal synthesis: failed (audit row missing — see daemon log) (anomaly)
+ *     - Journal synthesis: failed (Stage B <state>)                   (terminal failure)
+ *     - Journal synthesis: failed (Stage B success but daily file missing) (PUT lost)
+ *
+ * The verb (`skipped` vs `failed`) reflects whether Stage B was even
+ * attempted — `skipped` is reserved for the first-run case where the
+ * orchestrator never dispatched Stage B; everything else surfaces as
+ * `failed` so the audit-trail language matches reality.
+ *
+ * No LLM final-text parsing anywhere — every field is sourced from a
+ * structured channel: `agent_actions.metadata` (written by Stage A via
+ * `PATCH /api/agent-actions/self`), `agent_actions.result` (terminal
+ * state for each stage), and `daily/<date>.md` frontmatter (fs read).
+ */
+import type Database from "better-sqlite3";
+import type { AgentWriteTracker } from "../../safety/agent-write-tracker.js";
+import { type AgentDayWindowUtc } from "./journal-skeleton-builder.js";
+/** Action types Stage A and Stage B insert into `agent_actions`. */
+export declare const STAGE_A_ACTION_TYPE = "routine.morning_routine_today";
+export declare const STAGE_B_ACTION_TYPE = "routine.morning_routine_journal";
+/** Stage row shape used by the composer. Subset of `agent_actions`. */
+export interface StageActionRow {
+    result: "success" | "failed" | "partial" | "skipped" | "in_progress";
+    /** Parsed JSON. `{}` when the column was NULL or non-object. */
+    metadata: Record<string, unknown>;
+    /**
+     * daily-journal-daemon-write.md §4.7 — Stage B `agent_actions.detail`
+     * carries a discriminated `dailyWrite` block when the daemon-side
+     * composer ran. Three states map to the journal-line verbs:
+     *   - `"complete"` → "Journal: daily/<date>.md (N lines, M projects)"
+     *   - `"partial"`  → "Journal: daily/<date>.md (N lines, **partial — <reason>**)"
+     *   - `false`      → "Journal synthesis: failed (<reason>)"
+     *
+     * Absent on rows written before the §4.11 wiring landed; readers fall
+     * back to the file-presence heuristic for backward compatibility.
+     */
+    dailyWrite?: DailyWriteDetail | null;
+}
+/**
+ * Mirror of `DailyWriteAuditDetail` in `dispatcher-types.ts`. Re-declared
+ * here rather than imported to keep the appender's import graph stable
+ * (it sits below the dispatcher in the dep order today). The fields
+ * are read defensively — `parseDailyWriteDetail` validates the shape
+ * before consumption so a malformed row degrades to "field absent"
+ * rather than corrupting the audit line.
+ */
+export type DailyWriteDetail = {
+    ok: "complete";
+    bytesWritten?: number;
+    wroteMode?: "put" | "append_revision";
+} | {
+    ok: "partial";
+    bytesWritten?: number;
+    wroteMode?: "put" | "append_revision";
+    partialReason: "frontmatter_tag_missing" | "frontmatter_invalid_json" | "frontmatter_schema_invalid";
+} | {
+    ok: false;
+    reason: "stage_b_null" | "empty_output" | "body_tag_missing" | "write_failed";
+};
+export interface AgentJournalAppenderDeps {
+    db: Database.Database;
+    contextDir: string;
+    writeTracker?: Pick<AgentWriteTracker, "markWriting" | "unmark">;
+    onIndexableContextChange?: (relativePath: string) => void;
+}
+export interface AgentJournalAppenderArgs {
+    /** Routine's correlation id — used as `event_id` to find both stage rows. */
+    correlationId: string;
+    /** Today's agent-day, used in the `## YYYY-MM-DD morning routine` H2. */
+    morningDateStr: string;
+    /** Yesterday's agent-day, used as the `daily/<yesterday>.md` filename. */
+    yesterdayDateStr: string;
+    /**
+     * Yesterday's agent-day UTC window. Used to aggregate the agent-action
+     * breakdown into the `- Actions: ...` footprint line. The agent-action
+     * summary used to live in the user-facing `daily/<date>.md` `## Actions`
+     * section, but was moved here as part of the user-diary refocus: the
+     * user-side journal no longer carries agent telemetry, while the
+     * agent-side footprint (`journal/agent.md`) gains a single inline
+     * summary line so the breakdown remains discoverable to operators
+     * running `pnpm audit`. The orchestrator owns the timezone /
+     * dayBoundaryHour math; passing the window in keeps this module pure
+     * of config plumbing.
+     *
+     * **Required.** A silent omission would render the Actions line as
+     * `(none)` — indistinguishable from a legitimate zero-action day —
+     * masking a wiring bug for an entire 24h cycle until the next
+     * morning routine. Making the field required closes that hole at
+     * compile time. Tests that don't care about the Actions line can
+     * pass `EMPTY_AGENT_DAY_WINDOW_FOR_TESTS` and the aggregation will
+     * deterministically return zero rows.
+     */
+    agentDayWindow: AgentDayWindowUtc;
+}
+/**
+ * A degenerate UTC window for tests that exercise non-Actions-line
+ * branches of the appender. Aggregating `agent_actions` rows over a
+ * zero-width window deterministically returns zero rows, so the
+ * `- Actions: (none)` rendering is identical to the "no actions
+ * yesterday" production case.
+ *
+ * Exported instead of inlined in each test so a future change to the
+ * window shape (e.g. ISO string vs SQLite datetime) updates one
+ * constant rather than ~10 test fixtures.
+ */
+export declare const EMPTY_AGENT_DAY_WINDOW_FOR_TESTS: AgentDayWindowUtc;
+export type AgentJournalAppenderResult = {
+    ok: true;
+    entryText: string;
+} | {
+    ok: false;
+    reason: "stage_a_row_missing";
+};
+/**
+ * Load Stage A + Stage B `agent_actions` rows by `event_id`. Returns
+ * `null` for either side that has no row yet — the composer surfaces
+ * that as "skipped" / `(none)` lines rather than throwing.
+ *
+ * Exported for testing so seeded-DB fixtures can verify the row binding
+ * without exercising the fs side of the appender.
+ */
+export declare function loadMorningRoutineActionRows(db: Database.Database, correlationId: string): {
+    stageA: StageActionRow | null;
+    stageB: StageActionRow | null;
+};
+/** Action-breakdown facts used to render the `- Actions: ...` footprint line. */
+export interface ActionsSummaryInput {
+    /** Total `agent_actions` rows in yesterday's agent-day window. */
+    totalActions: number;
+    /**
+     * `agent_actions` rows grouped by `action_type`, ordered by count
+     * desc then action_type asc. The composer caps the inline rendering
+     * at `ACTIONS_TOP_N` types so the line stays single-line readable
+     * even for a busy day.
+     */
+    actionsByType: ReadonlyArray<{
+        actionType: string;
+        count: number;
+    }>;
+}
+/** Inputs the pure composer needs. Mirrors what `appendMorningRoutineJournalEntry` collects. */
+export interface JournalEntryComposeInputs {
+    morningDateStr: string;
+    yesterdayDateStr: string;
+    stageA: StageActionRow;
+    stageB: StageActionRow | null;
+    /** `null` when `daily/<yesterdayDateStr>.md` does not exist on disk. */
+    dailyJournalContent: string | null;
+    /**
+     * Yesterday's agent-action breakdown for the `- Actions: ...`
+     * footprint line. Sourced from `gatherJournalSkeletonFacts` against
+     * the agent-day window. Optional so unit tests focusing on the
+     * other composer fields don't have to thread the summary through;
+     * an absent value renders as `(none)` (semantically correct — no
+     * breakdown supplied means no actions to report). The end-to-end
+     * `appendMorningRoutineJournalEntry` always populates it from the
+     * SQLite aggregation.
+     */
+    actionsSummary?: ActionsSummaryInput;
+    /**
+     * Whether Stage B was attempted (i.e. `yesterday.md` existed when the
+     * orchestrator built Stage B's inputs — `buildStageBInputs` returns
+     * non-null iff yesterday.md is on disk). The end-to-end
+     * `appendMorningRoutineJournalEntry` derives this from a live
+     * `existsSync(yesterday.md)` check.
+     *
+     * Disambiguates two states that previously rendered identically as
+     * `Journal synthesis: skipped (no prior-day data)`:
+     *   - `false` → first-run / no prior-day data: legitimate skip.
+     *   - `true` AND `stageB === null` → Stage B was dispatched but its
+     *     `agent_actions` row never landed. This is a defence-in-depth
+     *     anomaly path: with the orchestrator-side failure-row write in
+     *     place (`recordStageFailure` → `audit.logError`), the only way
+     *     to reach this state is a rare SQLite write failure inside
+     *     `audit.logError` itself. Surface it as `Journal synthesis:
+     *     failed (audit row missing — see daemon log)` instead of
+     *     masking the failure as a first-run.
+     *
+     * Optional so unit tests that don't care about the disambiguation
+     * stay terse; when omitted the composer falls back to the legacy
+     * heuristic (`stageB === null` → first-run), preserving the
+     * pre-disambiguation behaviour for callers that haven't been
+     * updated.
+     */
+    stageBAttempted?: boolean;
+}
+/**
+ * Pure composer — every output byte is a deterministic function of the
+ * inputs. Exposed for unit tests so the prose can be pinned without
+ * the fs / DB harness.
+ */
+export declare function composeMorningRoutineJournalEntry(inputs: JournalEntryComposeInputs): string;
+/**
+ * Append the composed entry to `journal/agent.md`. Mirrors the write
+ * chokepoint that `PATCH /api/context/journal/agent?mode=append_to_file`
+ * exposes to the agent: snapshot the existing file into
+ * `md_file_snapshots`, write the new content atomically, then notify
+ * the write tracker + indexer so observers don't tag the write as a
+ * user-actor change.
+ */
+export declare function appendMorningRoutineJournalEntry(deps: AgentJournalAppenderDeps, args: AgentJournalAppenderArgs): Promise<AgentJournalAppenderResult>;
+/**
+ * Append a new top-level block (delimited by H2 heading) to the
+ * journal. When the file does not yet exist, seed it with the
+ * `# Agent journal` H1 + the entry. Otherwise trim trailing whitespace
+ * and join with a blank line.
+ *
+ * Retry idempotency: if `original` already contains a block whose H2
+ * heading matches `block`'s first line verbatim (i.e. the morning
+ * routine for this date emitted earlier in this run / a prior retry
+ * attempt), the existing block is replaced from its H2 to the start of
+ * the next H2 (or EOF) rather than producing a duplicate. This matches
+ * the dispatcher's retry chain semantics where Stage A re-fires on
+ * today.md health failure and the orchestrator re-invokes ⑥ — without
+ * this guard `pnpm audit` would see two entries for the same date.
+ * The replacement uses the LAST matching H2 occurrence so a legacy
+ * entry for the same date in deep history is preserved (defence-in-
+ * depth — re-running multiple weeks later still replaces only the
+ * most-recent attempt).
+ *
+ * Exposed for testing so the fresh-file / existing-file / retry
+ * branches can be pinned without the full appendMorningRoutineJournalEntry
+ * harness.
+ */
+export declare function appendBlockToJournal(original: string | null, block: string): string;
+export interface DailyJournalStats {
+    bodyLineCount: number;
+    projectsCount: number;
+}
+/**
+ * Pull body-line count + projects-array length from a `daily/<date>.md`
+ * body. Tolerant of both flow-style (`projects: [a, b, c]`) and list
+ * form (`projects:\n  - a\n  - b`); placeholder `projects: []` and
+ * absent field both count as zero. Body excludes the YAML frontmatter
+ * block.
+ *
+ * Exposed for testing so the parsing branches stay pinnable.
+ */
+export declare function inspectDailyJournal(content: string): DailyJournalStats;