opencode-matrixx-v2 0.0.0-stage → 1.0.0

package/dist/features/handoff/schema.d.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+/**
+ * Handoff YAML frontmatter + body Zod schemas.
+ *
+ * Pure schema definitions — no I/O, no side effects. Used by:
+ * - `validateHandoffYaml` (this folder) for parsing & validating handoff files
+ * - future write-side tooling to construct frontmatter programmatically
+ */
+export declare const GitHeadSchema: z.ZodObject<{
+    sha: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+    detached: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GitHead = z.infer<typeof GitHeadSchema>;
+export declare const HandoffFrontmatterSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    timestamp: z.ZodString;
+    git_head: z.ZodObject<{
+        sha: z.ZodString;
+        branch: z.ZodOptional<z.ZodString>;
+        detached: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    topics: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type HandoffFrontmatter = z.infer<typeof HandoffFrontmatterSchema>;
+export declare const HandoffKeyFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    purpose: z.ZodString;
+}, z.core.$strip>;
+export type HandoffKeyFile = z.infer<typeof HandoffKeyFileSchema>;
+export declare const HandoffDecisionSchema: z.ZodObject<{
+    decision: z.ZodString;
+    rationale: z.ZodString;
+}, z.core.$strip>;
+export type HandoffDecision = z.infer<typeof HandoffDecisionSchema>;
+export declare const HandoffSectionSchema: z.ZodObject<{
+    user_requests: z.ZodString;
+    goal: z.ZodString;
+    work_completed: z.ZodArray<z.ZodString>;
+    current_state: z.ZodString;
+    pending_tasks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    key_files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        purpose: z.ZodString;
+    }, z.core.$strip>>>;
+    important_decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        decision: z.ZodString;
+        rationale: z.ZodString;
+    }, z.core.$strip>>>;
+    explicit_constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    context_for_continuation: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HandoffSection = z.infer<typeof HandoffSectionSchema>;
+export declare const HandoffSchema: z.ZodObject<{
+    frontmatter: z.ZodObject<{
+        session_id: z.ZodString;
+        timestamp: z.ZodString;
+        git_head: z.ZodObject<{
+            sha: z.ZodString;
+            branch: z.ZodOptional<z.ZodString>;
+            detached: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        topics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    sections: z.ZodObject<{
+        user_requests: z.ZodString;
+        goal: z.ZodString;
+        work_completed: z.ZodArray<z.ZodString>;
+        current_state: z.ZodString;
+        pending_tasks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        key_files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            purpose: z.ZodString;
+        }, z.core.$strip>>>;
+        important_decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            decision: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>>;
+        explicit_constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        context_for_continuation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type HandoffData = z.infer<typeof HandoffSchema>;
+/**
+ * Validated handoff with the markdown body preserved.
+ * Returned by `validateHandoffYaml` on success.
+ */
+export type HandoffFileData = HandoffData & {
+    body: string;
+};

package/dist/features/handoff/storage.d.ts

@@ -0,0 +1,7 @@
+export declare function getHandoffFilePath(directory: string): string;
+export declare function getHandoffConsumedFilePath(directory: string): string;
+export declare function handoffFileExists(directory: string): boolean;
+export declare function readHandoffFile(directory: string): string | null;
+export declare function archiveHandoffFile(directory: string): boolean;
+export declare function writeHandoffFile(directory: string, content: string): boolean;
+export declare function ensureHandoffDir(directory: string): boolean;

package/dist/features/handoff/validate.d.ts

@@ -0,0 +1,22 @@
+import { type HandoffFileData } from "./schema";
+/**
+ * Result of validating a handoff markdown document.
+ */
+export type HandoffValidationResult = {
+    valid: true;
+    data: HandoffFileData;
+} | {
+    valid: false;
+    errors: string[];
+    data?: undefined;
+};
+/**
+ * Parse and validate a handoff markdown document.
+ *
+ * Reuses `parseFrontmatter` from `src/shared/frontmatter` to extract the
+ * YAML block, then validates with `HandoffSchema`. The markdown body is
+ * preserved in `data.body` so callers can render it without re-parsing.
+ *
+ * Never throws — returns a structured error result on any failure.
+ */
+export declare function validateHandoffYaml(content: string): HandoffValidationResult;

package/dist/features/hook-message-injector/constants.d.ts

@@ -0,0 +1 @@
+export { MESSAGE_STORAGE, OPENCODE_STORAGE, PART_STORAGE } from "../../shared";

package/dist/features/hook-message-injector/index.d.ts

@@ -0,0 +1,5 @@
+export { MESSAGE_STORAGE } from "./constants";
+export type { StoredMessage } from "./injector";
+export { findFirstMessageWithAgent, findFirstMessageWithAgentFromSDK, findNearestMessageWithFields, findNearestMessageWithFieldsFromSDK, injectHookMessage, resolveMessageContext, } from "./injector";
+export { invalidateSdkMessageCache } from "./sdk-message-cache";
+export type { MessageMeta, OriginalMessageContext, TextPart, ToolPermission } from "./types";

package/dist/features/hook-message-injector/injector.d.ts

@@ -0,0 +1,62 @@
+import type { SessionContextCarrier } from "../../shared/session-context-source";
+import type { OriginalMessageContext, ToolPermission } from "./types";
+export interface StoredMessage {
+    agent?: string;
+    model?: {
+        providerID?: string;
+        modelID?: string;
+        variant?: string;
+    };
+    tools?: Record<string, ToolPermission>;
+}
+export type MessageSource = SessionContextCarrier;
+export declare function findNearestMessageWithFieldsFromSDK(client: MessageSource, sessionID: string, timeoutMs?: number): Promise<StoredMessage | null>;
+/**
+ * Finds the FIRST (oldest) message with agent field using SDK (for beta/SQLite backend).
+ */
+export declare function findFirstMessageWithAgentFromSDK(client: MessageSource, sessionID: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Finds the nearest message with required fields (agent, model.providerID, model.modelID).
+ * Reads from JSON files - for stable (JSON) backend.
+ *
+ * **Version-gated behavior:**
+ * - On beta (SQLite backend): Returns null immediately (no JSON storage)
+ * - On stable (JSON backend): Reads from JSON files in messageDir
+ *
+ * @deprecated Use findNearestMessageWithFieldsFromSDK for beta/SQLite backend
+ */
+export declare function findNearestMessageWithFields(messageDir: string): StoredMessage | null;
+/**
+ * Finds the FIRST (oldest) message in the session with agent field.
+ * Reads from JSON files - for stable (JSON) backend.
+ *
+ * **Version-gated behavior:**
+ * - On beta (SQLite backend): Returns null immediately (no JSON storage)
+ * - On stable (JSON backend): Reads from JSON files in messageDir
+ *
+ * @deprecated Use findFirstMessageWithAgentFromSDK for beta/SQLite backend
+ */
+export declare function findFirstMessageWithAgent(messageDir: string): string | null;
+/**
+ * Injects a hook message into the session storage.
+ *
+ * **Version-gated behavior:**
+ * - On beta (SQLite backend): Logs warning and skips injection (writes are invisible to SQLite)
+ * - On stable (JSON backend): Writes message and part JSON files
+ *
+ * Features degraded on beta:
+ * - Hook message injection (e.g., continuation prompts, context injection) won't persist
+ * - Niobe hook's injected messages won't be visible in SQLite backend
+ * - Todo continuation enforcer's injected prompts won't persist
+ * - Ralph loop's continuation prompts won't persist
+ *
+ * @param sessionID - Target session ID
+ * @param hookContent - Content to inject
+ * @param originalMessage - Context from the original message
+ * @returns true if injection succeeded, false otherwise
+ */
+export declare function injectHookMessage(sessionID: string, hookContent: string, originalMessage: OriginalMessageContext): boolean;
+export declare function resolveMessageContext(sessionID: string, client: MessageSource, messageDir: string | null): Promise<{
+    prevMessage: StoredMessage | null;
+    firstMessageAgent: string | null;
+}>;

package/dist/features/hook-message-injector/sdk-message-cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-sessionID cache for native session context reads.
+ *
+ * Why this exists: the full transcript fetch is a 5s-timeout SDK/HTTP round trip
+ * that scales with SESSION LENGTH, not with the work of the tool being called.
+ * Several hooks resolve the same session's agent/model on every single tool call
+ * (see `isCallerOrchestrator` in src/shared/session-utils.ts and
+ * `getAgentFromSession` in src/hooks/oracle-md-only/agent-resolution.ts), so the
+ * same transcript was re-fetched repeatedly for the life of the session.
+ *
+ * We cache the RAW message list rather than each derived lookup, so both
+ * `findNearestMessageWithFieldsFromSDK` and `findFirstMessageWithAgentFromSDK`
+ * are served by a single fetch.
+ *
+ * Invalidation is TTL-based plus explicit:
+ *  - TTL bounds staleness, because a new tool call CAN append a message that
+ *    changes the "nearest message with an agent" answer. A session-lifetime
+ *    cache would be incorrect.
+ *  - `invalidateSdkMessageCache(sessionID)` lets the event hook drop a session
+ *    the moment its state is known to have changed.
+ */
+/**
+ * Returns the cached message list for a session, or undefined on miss/expiry.
+ * Expired entries are removed eagerly so the map cannot grow unboundedly.
+ */ export declare function getCachedSdkMessages(sessionID: string): unknown[] | undefined;
+/**
+ * Stores a message list for a session. Stores a reference to the array, not a
+ * clone — callers must treat cached arrays as read-only.
+ */
+export declare function setCachedSdkMessages(sessionID: string, messages: unknown[], ttlMs?: number): void;
+/** Drops the cached transcript for one session, or all sessions if omitted. */
+export declare function invalidateSdkMessageCache(sessionID?: string): void;
+/** Test seam — mirrors the `_resetForTesting` convention in features/session-state. */
+export declare function _resetSdkMessageCache(): void;

package/dist/features/hook-message-injector/types.d.ts

@@ -0,0 +1,46 @@
+export type ToolPermission = boolean | "allow" | "deny" | "ask";
+export interface MessageMeta {
+    id: string;
+    sessionID: string;
+    role: "user" | "assistant";
+    time: {
+        created: number;
+        completed?: number;
+    };
+    agent?: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    path?: {
+        cwd: string;
+        root: string;
+    };
+    tools?: Record<string, ToolPermission>;
+}
+export interface OriginalMessageContext {
+    agent?: string;
+    model?: {
+        providerID?: string;
+        modelID?: string;
+        variant?: string;
+    };
+    path?: {
+        cwd?: string;
+        root?: string;
+    };
+    tools?: Record<string, ToolPermission>;
+}
+export interface TextPart {
+    id: string;
+    type: "text";
+    text: string;
+    synthetic: boolean;
+    time: {
+        start: number;
+        end: number;
+    };
+    messageID: string;
+    sessionID: string;
+}

package/dist/features/knowledge-hub/index.d.ts

@@ -0,0 +1,3 @@
+export type { LoadedHub } from "./loader";
+export { expandHubPath, loadKnowledgeHubs } from "./loader";
+export { resolveKnowledgeFile } from "./resolver";

package/dist/features/knowledge-hub/loader.d.ts

@@ -0,0 +1,11 @@
+import { type KnowledgeConfig, type KnowledgeHub } from "../../config/schema/knowledge";
+export interface LoadedHub {
+    name: string;
+    root: string;
+    indexPath: string;
+    scope: KnowledgeHub["scope"];
+    mode: KnowledgeHub["mode"];
+    exclude: string[];
+}
+export declare function expandHubPath(rawPath: string, projectDir?: string): string;
+export declare function loadKnowledgeHubs(config: KnowledgeConfig | KnowledgeHub[], projectDir?: string): LoadedHub[];

package/dist/features/knowledge-hub/resolver.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedHub } from "./loader";
+export declare function resolveKnowledgeFile(hubs: LoadedHub[], ref: string): string | null;

package/dist/features/mission-state/atomic-write.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The tmp+rename primitive every plan write goes through.
+ *
+ * Split out of `plan-storage.ts` to keep that module under the 200-LOC ceiling.
+ * The target is never written in place — it is only ever REPLACED by rename — so
+ * a crash mid-write leaves the previous bytes intact rather than a truncated file.
+ */
+export declare function atomicWrite(filePath: string, content: string): boolean;

package/dist/features/mission-state/completion.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Plan Completion Overlay
+ *
+ * Pure read-only verdict over the single checkbox implementation
+ * (`countPlanProgressFromContent` in `storage.ts`, regexes in `constants.ts`).
+ * This module NEVER counts checkboxes itself — it imports the counter and
+ * adds the front-matter `status` AND-gate from `plan-contract/schema.ts`.
+ *
+ * Verdict rule: `complete` iff (all boxes checked AND status == "completed").
+ * Any checkbox/status disagreement yields `mismatch-warn` (warn-only; the
+ * caller surfaces an advisory, never auto-flips). Zero-task plans
+ * (`needsTriage`, e.g. humanize 0/4 or dwfinance 0/5 design docs) NEVER
+ * verdict-complete — so a gap can never masquerade
+ * as done (silent-failure guard).
+ */
+import { PLAN_STATUS_ORDER } from "../plan-contract/schema";
+import type { PlanProgress } from "./types";
+/** Authoritative front-matter status values (subset of plan-contract enum). */
+export type FrontMatterStatus = (typeof PLAN_STATUS_ORDER)[number];
+/** Minimal front-matter input the overlay reads; never written here. */
+export interface CompletionFrontMatter {
+    /** Authoritative `status` from front-matter; unknown/absent becomes null. */
+    status: string;
+}
+/** Overlay verdict: complete, incomplete, or warn-only disagreement. */
+export type CompletionVerdict = "complete" | "incomplete" | "mismatch-warn";
+/** Read-only resolution result; checkbox counts are unchanged. */
+export interface PlanCompletion {
+    /** Checkbox progress from the single counter (imported, never recomputed). */
+    checkbox: PlanProgress;
+    /** Normalized front-matter status, or null when absent/unknown. */
+    status: FrontMatterStatus | null;
+    /** Overlay verdict per the AND-gate rule. */
+    verdict: CompletionVerdict;
+}
+/**
+ * Resolve plan completion from body checkboxes + front-matter status.
+ *
+ * Pure and read-only: checkbox counts come from
+ * `countPlanProgressFromContent`; the AND-gate delegates to `isPlanComplete`.
+ * Triage (`needsTriage`, zero tasks) short-circuits to a non-complete
+ * verdict, so empty/design docs can never
+ * report complete.
+ */
+export declare function resolvePlanCompletion(content: string, frontMatter: CompletionFrontMatter | null): PlanCompletion;
+/**
+ * Human-readable advisory for a `mismatch-warn` verdict.
+ *
+ * result into an existing warning channel only when non-null. Callers that
+ * lack front-matter should skip the overlay (nothing authoritative to agree
+ * with) and leave the verdict uncomputed.
+ * Returns null unless the verdict is `mismatch-warn` — callers spread the
+ * result into an existing warning channel only when non-null. Callers that
+ * lack front-matter should skip the overlay (nothing authoritative to agree
+ * with) and leave the verdict uncomputed.
+ * Never throws; never touches checkbox counts.
+ */
+export declare function formatCompletionWarning(result: PlanCompletion): string | null;

package/dist/features/mission-state/constants.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mission State Constants
+ */
+export declare const MISSION_DIR = ".matrixx";
+export declare const MISSION_FILE = "mission.json";
+/** Oracle planner plan directory pattern */
+export declare const ORACLE_PLANS_DIR = ".matrixx/plans";
+/**
+ * Plan Persistence Constants
+ */
+/** Relative path from project root to plans directory */
+export declare const PLANS_DIR = ".matrixx/plans";
+/** Subdir of PLANS_DIR holding archived stale plans; excluded from listings. */
+export declare const PLANS_ARCHIVE_DIR_NAME = "_archive";
+/** Default staleness window (hours) shared by task + plan archival. */
+export declare const DEFAULT_STALE_AFTER_HOURS = 24;
+/** HTML comment marker for machine metadata at the end of a plan file */
+export declare const META_TAG_PREFIX = "<!-- plan-persister:";
+export declare const META_TAG_SUFFIX = "-->";
+/** Safety cap: max bytes for a single plan file read */
+export declare const MAX_PLAN_FILE_BYTES = 140000;
+/**
+ * Resolve the effective plan file cap from plugin config, falling back to
+ * `MAX_PLAN_FILE_BYTES` when unset. Mirrors the
+ * `cfg?.detection?.max_scan_bytes ?? 64*1024` fallback pattern.
+ */
+export declare function resolvePlanCap(config?: {
+    plans?: {
+        max_plan_file_bytes?: number;
+    };
+} | undefined): number;
+/**
+ * The single byte ruler for plan content.
+ *
+ * Every plan size limit compared against this value (`MAX_PLAN_FILE_BYTES`,
+ * `MAX_PLAN_READ_RENDERED_BYTES`, the plan-contract size cap) is a TRUE UTF-8
+ * byte limit — never a UTF-16 code-unit (`.length`) count. A `.length` ruler
+ * undercounts CJK/emoji content by up to 3x and silently reports compliance.
+ */
+export declare function measurePlanBytes(content: string): number;
+/**
+ * Plan Checkbox Patterns
+ *
+ * Single source of truth for plan progress counting (see getPlanProgress).
+ * All patterns are anchored to column 0: indented sub-checkboxes
+ * (acceptance criteria, Definition-of-Done nests) never count.
+ * Do NOT inline checkbox regexes elsewhere — import these instead.
+ */
+/** Top-level unchecked box: `- [ ]` or `* [ ]` */
+export declare const TOP_UNCHECKED_RE: RegExp;
+/** Top-level checked box: `- [x]` / `- [X]` (case-insensitive) */
+export declare const TOP_CHECKED_RE: RegExp;
+/** Numbered unchecked task (Oracle format): `- [ ] 1. Task` */
+export declare const NUMBERED_UNCHECKED_RE: RegExp;
+/** Numbered checked task (Oracle format): `- [x] 2. Task` */
+export declare const NUMBERED_CHECKED_RE: RegExp;

package/dist/features/mission-state/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./completion";
+export * from "./constants";
+export * from "./plan-storage";
+export * from "./reconcile";
+export * from "./rehydrate";
+export * from "./storage";
+export * from "./types";

package/dist/features/mission-state/plan-file-read.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Plan file readers.
+ *
+ * Split out of `plan-storage.ts` for the 200-LOC ceiling. The two readers are
+ * deliberately separate functions rather than one with a `skipCap` flag: the cap
+ * in `readPlanFile` is the defensive whole-file guard, and a boolean on the
+ * signature would put "turn it off" one edit away from a whole-file call site.
+ */
+/**
+ * Read a plan file's content.
+ * Returns null if the file does not exist, is too large, or cannot be read.
+ */
+export declare function readPlanFile(planPath: string, cap?: number): string | null;
+/** Read a plan file for a SPAN read, skipping the cap. See the module header. */
+export declare function readPlanFileSpan(planPath: string): string | null;

package/dist/features/mission-state/plan-storage.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Plan Persistence Storage
+ *
+ * Atomic file operations for plan files.
+ * Reuses the write-temp-then-rename pattern from handoff/storage.ts.
+ */
+import type { PlanMeta } from "./types";
+export { atomicWrite } from "./atomic-write";
+export { readPlanFile, readPlanFileSpan } from "./plan-file-read";
+/**
+ * Ensure the .matrixx/plans directory exists under the project root.
+ */
+export declare function ensurePlanDir(directory: string): boolean;
+/**
+ * Write content to a plan file using atomic write.
+ * Ensures the plan directory exists first.
+ */
+export declare function writePlanFile(directory: string, planPath: string, content: string): boolean;
+/**
+ * Verification-style guard: boxes matching verify/verification/checklist/
+ * definition-of-done/final check with zero task overlap are never
+ * force-completed — state kept, line reported via `flaggedVerification`.
+ */
+export declare const VERIFICATION_STYLE_RE: RegExp;
+/** Lowercase, strip punctuation/numbers, split tokens, drop stop-words. */
+export declare function normalizeCheckboxText(text: string): string[];
+export declare const isVerificationStyle: (text: string) => boolean;
+/**
+ * Token overlap: match on >= 2 shared content tokens, or on shorter-side
+ * ratio >= 0.5 with normalized-set equality (equality keeps exact matches
+ * like "Task A"; without it one generic word cross-matches every sibling,
+ * e.g. "Task D" would flip on completed "Task A").
+ */
+export declare function checkboxOverlap(a: string, b: string): {
+    shared: number;
+    score: number;
+    matched: boolean;
+};
+export interface SyncCheckboxesResult {
+    content: string;
+    flaggedVerification: string[];
+}
+/**
+ * Sync checkboxes to todos by token overlap (indented lines sync too, though
+ * Task 2 counting ignores them). Best overlap wins, ties go first. Checked
+ * boxes never uncheck ([ ] → [x] only); unmatched lines keep state.
+ */
+export declare function syncCheckboxesDetailed(content: string, todos: Array<{
+    content: string;
+    status: string;
+}>): SyncCheckboxesResult;
+/** String-only wrapper (backward compatible with plan-persister hook). */
+export declare function syncCheckboxes(content: string, todos: Array<{
+    content: string;
+    status: string;
+}>): string;
+/**
+ * Append or replace the <!-- plan-persister: ... --> metadata comment.
+ *
+ * If a comment already exists at the end of the file, it is replaced in-place.
+ * Otherwise, the tag is appended after the last line.
+ */
+export declare function upsertMetadataComment(content: string, meta: PlanMeta): string;
+/**
+ * Extract PlanMeta from an HTML comment, or null if absent/malformed.
+ */
+export declare function parseMetadataComment(content: string): PlanMeta | null;

package/dist/features/mission-state/reconcile.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Plan reconciliation + stale-plan archival policy.
+ *
+ * The reconciler re-runs the Tasks 3-4 linkage pass (checkboxOverlap +
+ * verification guard from plan-storage) with a confidence gate: only
+ * high-confidence token overlap auto-checks, the rest is reported for
+ * manual plan_update. Runs are idempotent — a converged plan yields no writes.
+ *
+ * Archival moves stale orphans to .matrixx/plans/_archive/ (never deletes).
+ */
+import type { MatrixxConfig } from "../../config/schema";
+export interface ReconcileTodo {
+    content: string;
+    status: string;
+}
+export interface ReconcileResult {
+    content: string;
+    checked: string[];
+    lowConfidence: string[];
+    flaggedVerification: string[];
+    changed: boolean;
+}
+export interface ReconcileFileResult extends ReconcileResult {
+    wrote: boolean;
+}
+/**
+ * High-confidence gate: token overlap matched (Task 3 thresholds) AND the
+ * box is not verification-flagged. Verification-style boxes with genuine
+ * overlap still flip (overlap wins); zero-overlap verification boxes land
+ * in flaggedVerification and never auto-check.
+ */
+export declare function isHighConfidence(boxText: string, todoContent: string, flaggedVerification?: string[]): boolean;
+/** Reconcile plan content against runtime todos; pure, no disk writes. */
+export declare function reconcilePlanContent(content: string, todos: ReconcileTodo[]): ReconcileResult;
+/** Reconcile one plan file; writes only when content changed (idempotent). */
+export declare function reconcilePlanFile(planPath: string, todos: ReconcileTodo[]): ReconcileFileResult;
+/** Invocation point for start-work: reconcile only when plans compete (>1). */
+export declare function shouldReconcileOnStartWork(incompleteCount: number): boolean;
+export interface ActiveTaskSubjects {
+    subjects: string[];
+    unknownTaskFiles: string[];
+}
+/**
+ * Subjects of active (pending/in_progress) tasks. Strict-schema drops
+ * (readJsonSafe -> null) are counted + logged as unknown — never treated
+ * as completed, never silently ignored.
+ */
+export declare function readActiveTaskSubjects(directory: string, config?: Partial<MatrixxConfig>): ActiveTaskSubjects;
+/** A plan whose file cannot be stat'ed is treated as fresh (not stale). */
+export declare function isStaleByMtime(planPath: string, staleAfterHours?: number): boolean;
+export type ArchiveDecision = "active-plan" | "linked-active-tasks" | "fresh" | "unreadable" | "stale-orphan";
+/** Archive candidacy: stale mtime AND zero linked active tasks AND not active. */
+export declare function isArchiveCandidate(planPath: string, content: string | null, subjects: string[], staleAfterHours: number, activePlan?: string | null): {
+    candidate: boolean;
+    reason: ArchiveDecision;
+};
+export interface ArchiveScanOptions {
+    staleAfterHours?: number;
+    activePlan?: string | null;
+    activeTaskSubjects?: string[];
+    config?: Partial<MatrixxConfig>;
+    dryRun?: boolean;
+}
+export interface ArchiveResult {
+    candidates: string[];
+    moved: string[];
+    unknownTaskFiles: string[];
+    before: number;
+    after: number;
+}
+/**
+ * Move stale orphans to _archive/ preserving bytes (incl. plan-persister
+ * meta). Dry-run reports candidates with zero moves. Never deletes.
+ */
+export declare function archiveStalePlans(directory: string, opts?: ArchiveScanOptions): ArchiveResult;
+export interface MissionReconcileOptions {
+    dryRun?: boolean;
+    staleAfterHours?: number;
+    activeTaskSubjects?: string[];
+    config?: Partial<MatrixxConfig>;
+}
+export interface MissionReconcileResult {
+    wrote: boolean;
+    reason: string;
+    candidates: string[];
+    moved: string[];
+    unknownTaskFiles: string[];
+    suggestion?: string;
+}
+/**
+ * Mission-aware orphan backfill (dry-run-first; default dryRun: true).
+ * Missing mission.json -> `{ wrote: false, reason: "no-mission-state" }` + stale-orphan
+ * candidates via isArchiveCandidate, zero writes, suggests start-work. Checkbox flips
+ * never happen here: any box rewrite stays on reconcilePlanFile/isHighConfidence path.
+ */
+export declare function reconcileMissionState(directory: string, opts?: MissionReconcileOptions): MissionReconcileResult;

package/dist/features/mission-state/rehydrate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plan Persistence Rehydration
+ *
+ * Builds rehydration context from mission state + plan file for injection
+ * after compaction or session start.
+ */
+import type { RehydrationContext } from "./types";
+export declare const MAX_REHYDRATION_BYTES = 8000;
+export declare const MAX_TOTAL_COMPACTION_BYTES = 11000;
+/**
+ * Truncate a string to at most maxBytes UTF-8 bytes without splitting
+ * a multibyte sequence. Byte-based (Buffer.byteLength), never .length.
+ */
+export declare function truncateUtf8ToBytes(value: string, maxBytes: number): string;
+/** Combined injector prompt + rehydration directive size in UTF-8 bytes. */
+export declare function measureCombinedCompactionBytes(injectorPrompt: string, directive: string): number;
+/**
+ * Build a rehydration context from mission state + plan file.
+ *
+ * Returns null when:
+ * - No mission file exists
+ * - Mission has no active_plan
+ * - Plan file is missing
+ * - Plan is 100% complete (no point rehydrating a finished plan)
+ */
+export declare function buildRehydrationContext(directory: string): RehydrationContext | null;
+/**
+ * Find active plan path from mission state.
+ */
+export declare function findActivePlan(directory: string): string | null;