opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/features/plan-contract/section-registry.d.ts

@@ -0,0 +1,87 @@
+export { CONSENSUS_H3_SEEDS } from "./section-registry-h3";
+/**
+ * Return the depth of an H2/H3 heading line, or `null` when `line` is not a
+ * `#{2,3}` heading. Used only to label an escape-hatch `custom` section; a
+ * selector with no marker is unknown-depth, not H2.
+ */
+export declare function extractHeadingLevel(line: string): SectionLevel | null;
+/** Heading depth of a registry entry. */
+export type SectionLevel = 2 | 3;
+/** One registry row: stable id, depth, canonical heading text, normalized key. */
+export interface SectionRegistryEntry {
+    /** Stable kebab-case identifier, e.g. `verification-strategy`. */
+    id: string;
+    /** Markdown heading depth. */
+    level: SectionLevel;
+    /** Canonical heading text, exactly as it appears in the plan. */
+    heading: string;
+    /** Normalized comparison key — the output of {@link normalizeSectionKey}. */
+    key: string;
+}
+/** Raw input accepted by {@link buildSectionRegistry}. */
+export interface SectionRegistrySeed {
+    heading: string;
+    level: SectionLevel;
+}
+/**
+ * `custom` is the ESCAPE HATCH, not a failure: a heading absent from the
+ * registry is a legitimate plan extension (the 35-plan corpus has 95 distinct
+ * H2 texts and 238 distinct H3s). It carries a derived `id` and the `rawText`
+ * it was addressed by, so a custom section is as addressable as a registry
+ * one. It deliberately has NO `message` key, so it can never be mistaken for
+ * the `ambiguous` failure, and the number of custom sections is never capped.
+ */
+export type SectionResolution = {
+    kind: "resolved";
+    entry: SectionRegistryEntry;
+} | {
+    kind: "custom";
+    selector: string;
+    rawText: string;
+    id: string;
+    key: string;
+    level: SectionLevel | null;
+} | {
+    kind: "ambiguous";
+    selector: string;
+    key: string;
+    candidates: SectionRegistryEntry[];
+    message: string;
+};
+/**
+ * Normalize arbitrary heading text or a registry key to its canonical
+ * kebab-case comparison form (identical to a registry entry's `id`).
+ * Pure and idempotent. Exported for tests and for callers that pre-index
+ * headings.
+ */
+export declare function normalizeSectionKey(text: string): string;
+/**
+ * Return the text after an H2/H3 marker, or `null` when `line` is not a `#{2,3}`
+ * heading. Mirrors the `H2_RE` style at `validate.ts:22` — it does NOT replace
+ * `DOD_HEADING_RE` (H2–H4), which stays authoritative.
+ */
+export declare function extractHeadingText(line: string): string | null;
+/** Build a registry from explicit seeds, deriving ids and keys from headings. */
+export declare function buildSectionRegistry(seeds: readonly SectionRegistrySeed[]): SectionRegistryEntry[];
+/** The derived H2 registry — one entry per `CANONICAL_SECTIONS` item, in order. */
+export declare const SECTION_REGISTRY: readonly SectionRegistryEntry[];
+/** The derived H3 consensus registry — ids come from the same normalizer. */
+export declare const H3_SECTION_REGISTRY: readonly SectionRegistryEntry[];
+/**
+ * Compile-time exhaustiveness gate. `tsc` checks `src/` but EXCLUDES `tests/`
+ * (see `tsconfig.json`), so this is where the union's closure is actually
+ * enforced: adding a variant to {@link SectionResolution} without adding it to
+ * this table is a build error.
+ */
+export type SectionResolutionKind = SectionResolution["kind"];
+/** The full H2 + H3 registry — every heading the resolver recognises. */
+export declare const PLAN_SECTION_REGISTRY: readonly SectionRegistryEntry[];
+/**
+ * Resolve a selector (raw heading text, an `## `/`### ` line, or a kebab id)
+ * against `entries` (defaults to the full H2+H3 {@link PLAN_SECTION_REGISTRY}).
+ *
+ * Returns `ambiguous` with EVERY candidate when more than one entry matches,
+ * `custom` when none does (the escape hatch, never an error), and `resolved`
+ * otherwise.
+ */
+export declare function resolveSectionSelector(selector: string, entries?: readonly SectionRegistryEntry[]): SectionResolution;

package/dist/features/plan-contract/skeleton.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Render the full canonical Oracle plan markdown skeleton — the content between
+ * the `\`\`\`markdown` fences of {@link ORACLE_PLAN_TEMPLATE}.
+ */
+export declare function renderPlanSkeleton(): string;

package/dist/features/plan-contract/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Plan Contract Types
+ *
+ * Structured view of an Oracle work plan: parsed sections, numbered tasks,
+ * definition-of-done lines, and optional YAML front-matter.
+ */
+import type { PlanSection } from "./constants";
+export type { PlanSection };
+/** A single numbered TODO task parsed from a plan. */
+export interface PlanTask {
+    /** Task number as written in the plan (e.g. `1` in `- [ ] 1. ...`). */
+    n: number;
+    /** Task title text following the number. */
+    title: string;
+    /** Whether the task checkbox is checked. */
+    checked: boolean;
+    /** 1-based line number of the task within the plan file. */
+    line: number;
+    /** Stable LINE#ID anchor for hashline-scoped edits. */
+    anchor: string;
+}
+/** Severity-neutral diagnostic emitted while validating a plan contract. */
+export interface PlanContractWarning {
+    /** Machine-readable warning code. */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** 1-based line the warning refers to, when known. */
+    line?: number;
+}
+/** Outcome of validating a plan against the contract. */
+export interface PlanContractResult {
+    /** True when no errors were produced (warnings may still be present). */
+    ok: boolean;
+    /** Non-fatal contract deviations. */
+    warnings: PlanContractWarning[];
+    /** Fatal contract violations. */
+    errors: string[];
+}
+/** Lifecycle status carried by a plan's YAML front-matter. */
+export type PlanStatus = "pending" | "in_progress" | "completed";
+/** Structured YAML front-matter block parsed from a plan file. */
+export interface PlanFrontMatter {
+    /** Current plan lifecycle status. */
+    status: PlanStatus;
+    /** Monotonic revision counter. */
+    revision: number;
+    /** Execution phase label, when present. */
+    phase?: string;
+    /** Execution wave label, when present. */
+    wave?: string;
+    /** Task ids this plan depends on. */
+    deps?: string[];
+    /** Task ids blocked by this plan. */
+    blockedBy?: string[];
+}

package/dist/features/plan-contract/validate.d.ts

@@ -0,0 +1,12 @@
+import type { PlanContractResult } from "./types";
+export type { HashlineAnchors, Heading } from "./parse";
+export { collectHeadings, normalizeSectionTitle, parsePlanContract, parsePlanTasks } from "./parse";
+/**
+ * Validate plan content against the canonical section contract.
+ *
+ * PERMANENTLY ADVISORY: section findings are warnings and never block. A
+ * hard-fail mode was removed deliberately — it would turn authoring guidance
+ * into a rejection and invite edit-retry loops over plans that were never
+ * wrong. Do not reintroduce it; `errors` is reserved for empty content.
+ */
+export declare function validatePlanContract(content: string, cap?: number): PlanContractResult;

package/dist/features/preset-state/manager.d.ts

@@ -0,0 +1,5 @@
+export declare function setSessionPreset(sessionID: string, presetName: string): void;
+export declare function getSessionPreset(sessionID: string): string | undefined;
+export declare function clearSessionPreset(sessionID: string): void;
+/** @internal */
+export declare function _resetPresetStateForTesting(): void;

package/dist/features/rtk-routing/routing-block.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared routing block for RTK shell discipline.
+ *
+ * Short reminder (per D3: ≤12 content lines) injected into the system prompt
+ * when RTK enforcement is active. Mentions only `rtk` + the rewriter hook;
+ * never other routing blocks or ctx tools.
+ */
+export declare const MATRIXX_RTK_MARKER = "<rtk_discipline>";
+/**
+ * Build the full routing block that is injected into the system prompt.
+ * Idempotence is the caller's concern: check for {@link MATRIXX_RTK_MARKER}
+ * before inserting, using {@link containsRtkMarker}.
+ */
+export declare function buildRtkRoutingBlock(): string;
+/**
+ * True when the marker is already present in any system message — used for
+ * idempotence so the block is never injected twice into the same prompt.
+ */
+export declare function containsRtkMarker(system: readonly string[]): boolean;

package/dist/features/rtk-routing/system-transform.d.ts

@@ -0,0 +1,43 @@
+import type { MatrixxConfig } from "../../config";
+import type { MatrixxContext } from "../../plugin/context";
+import type { Hooks } from "../../plugin/legacy-hooks";
+export declare const HOOK_NAME = "rtk-routing";
+/** Stable injector id for injection-notifier dedupe. */
+export declare const RTK_INJECTOR_ID = "rtk-routing";
+/** Short toast title for the RTK routing-block injection. */
+export declare const RTK_NOTICE_TITLE = "RTK injection";
+/** Toast message — kept free of keyword-detector triggers (loop-safe). */
+export declare const RTK_NOTICE_MESSAGE = "RTK discipline active";
+type SystemTransformHandler = NonNullable<Hooks["experimental.chat.system.transform"]>;
+export interface RtkSystemTransformOptions {
+    hookEnabled?: boolean;
+    hasBash?: (agentName?: string) => boolean;
+    which?: (binary: string) => string | null;
+}
+/**
+ * Simple FNV-1a string hash (hex) used as the injection-content dedupe key.
+ * Same content → same hash (toast suppressed); changed content → new toast.
+ */
+export declare function hashRtkInjectionContent(content: string): string;
+/**
+ * Builds the `experimental.chat.system.transform` handler that injects the
+ * RTK shell-discipline routing block into every system prompt.
+ *
+ * Fail-open by design: the hook is guidance, never enforcement, so any error
+ * (malformed output, unexpected SDK shape) returns without throwing and
+ * simply leaves the prompt untouched.
+ *
+ * Seams (test-only overrides, never production paths):
+ * - `which` — injected binary probe, forwarded to the resolver so tests can
+ *   simulate a present binary without touching PATH.
+ * - `hookEnabled` — captured at factory time alongside the resolver result;
+ *   lets tests flip the gate without touching hook config.
+ * - `hasBash` — per-agent bash probe; receives the agent name when the
+ *   caller knows it, defaults to the global available-tool-names signal.
+ *
+ * When `ctx` is provided, a toast is fired via `notifyInjection` exactly once
+ * per session per block version — only after the splice, never on the
+ * marker-present early-return path. Dedupe is handled inside the notifier.
+ */
+export declare function createRtkSystemTransformHook(pluginConfig: MatrixxConfig, opts?: RtkSystemTransformOptions, ctx?: MatrixxContext): SystemTransformHandler;
+export {};

package/dist/features/session-memory/compacting.d.ts

@@ -0,0 +1,9 @@
+import type { SummaryNode } from "./summary";
+export declare const COMPACTING_SNIPPET_BUDGET: 1200;
+export type CompactingSnippetInput = string | SummaryNode[] | string[];
+/**
+ * Pure deterministic budgeted snippet for the compaction append path.
+ * No LLM, no IO. Joins node snippets (or lines) and truncates
+ * verbatim to `budget` (default 1200) even on over-budget input.
+ */
+export declare function getCompactingSnippet(input?: CompactingSnippetInput, budget?: number): string;

package/dist/features/session-memory/constants.d.ts

@@ -0,0 +1,18 @@
+export declare const MEMORY_DIR_NAME: ".matrixx";
+export declare const MEMORY_SUBDIR_NAME: "memory";
+export declare const MEMORY_FILE_NAME: "memory.jsonl";
+export declare const MEMORY_LOCK_FILE_NAME: ".lock";
+export declare const STALE_LOCK_THRESHOLD_MS: 30000;
+export declare const LOCK_RETRY_COUNT: 4;
+export declare const DEFAULT_PINNED: false;
+export declare const DEFAULT_REMOVED: false;
+export declare const DEFAULT_SCOPE: "session";
+export declare const SYNTHETIC_MESSAGE_PREFIXES: readonly ["<task-notification>", `<${string}>`, "<context_guidance>", "<tool-result>"];
+export type SyntheticMessagePrefix = (typeof SYNTHETIC_MESSAGE_PREFIXES)[number];
+/**
+ * True-synthetic gate: startsWith on the known prefixes (kept for true
+ * synthetic only) plus the shared closed-table helper for control
+ * elements and paired presentational blocks.
+ * Text-only: callers pass payload strings (input.text / blob).
+ */
+export declare function isSyntheticMessage(text: string): boolean;

package/dist/features/session-memory/index.d.ts

@@ -0,0 +1,13 @@
+export type { CompactingSnippetInput } from "./compacting";
+export { COMPACTING_SNIPPET_BUDGET, getCompactingSnippet } from "./compacting";
+export { DEFAULT_PINNED, DEFAULT_REMOVED, DEFAULT_SCOPE, isSyntheticMessage, LOCK_RETRY_COUNT, MEMORY_DIR_NAME, MEMORY_FILE_NAME, MEMORY_LOCK_FILE_NAME, MEMORY_SUBDIR_NAME, STALE_LOCK_THRESHOLD_MS, SYNTHETIC_MESSAGE_PREFIXES } from "./constants";
+export type { RecallCandidate, RecallHit, RecallOptions, RecallScope, RecallScopeProfile } from "./recall";
+export { filterPrefixedTools, isSyntheticCandidate, recall, renderRecallContext, resolveRecallScope, truncateRecall } from "./recall";
+export type { PruneResult, RetentionPolicy, RetentionReport } from "./retention";
+export { prune, pruneReport, retentionCutoff } from "./retention";
+export type { ListMemoryOptions } from "./storage";
+export { acquireLock, acquireLockWithRetry, appendMemoryEntry, generateMemoryId, getMemoryDir, getMemoryFilePath, getProjectMemoryDir, listMemoryEntries, readMemoryEntries, writeJsonAtomic, } from "./storage";
+export type { ShapeSummaryOptions, SummaryNode, SummarySource } from "./summary";
+export { shapeSummaryNodes, truncateSummary } from "./summary";
+export type { MemoryEntry, MemoryEntryInput, MemoryScope } from "./types";
+export { MemoryEntryInputSchema, MemoryEntrySchema, MemoryScopeSchema } from "./types";

package/dist/features/session-memory/recall.d.ts

@@ -0,0 +1,64 @@
+import type { MemoryEntry } from "./types";
+export type RecallScope = "session" | "project" | "global" | "all";
+export interface RecallCandidate {
+    id: string;
+    sessionId: string;
+    messageId: string;
+    scope: RecallScope;
+    text: string;
+    toolName?: string;
+    kind?: "message" | "summary" | "artifact";
+}
+export interface RecallScopeProfile {
+    worktree: string;
+    scope?: RecallScope;
+}
+export interface RecallOptions {
+    scope?: RecallScope;
+    sessionId?: string;
+    worktree?: string;
+    scopeProfiles?: RecallScopeProfile[];
+    scopeDefault?: RecallScope;
+    ignoreToolPrefixes?: string[];
+    perMessageBudget?: number;
+    maxChars?: number;
+    minTokens?: number;
+    maxMessageHits?: number;
+    maxSummaryHits?: number;
+    maxArtifactHits?: number;
+    budgets?: Record<RecallScope, number>;
+}
+export interface RecallHit {
+    kind: "message" | "summary" | "artifact";
+    id: string;
+    sessionId: string;
+    messageId: string;
+    scope: RecallScope;
+    snippet: string;
+}
+/**
+ * Scope precedence: explicit > profile (worktree match) > default.
+ * Pure — no IO.
+ */
+export declare function resolveRecallScope(options?: RecallOptions): RecallScope;
+/** Verbatim truncate — mirrors upstream truncate(), no text mutation beyond cut. */
+export declare function truncateRecall(text: string, limit: number): string;
+/**
+ * Shared-backed synthetic gate (single source: constants.isSyntheticMessage,
+ * which references the shared closed table). Text-only on payload strings.
+ */
+export declare function isSyntheticCandidate(text: string): boolean;
+/**
+ * Non-destructive ctx_-style prefix filter: skips candidates whose toolName
+ * starts with any ignoreToolPrefixes entry. Input array is never mutated.
+ */
+export declare function filterPrefixedTools(candidates: RecallCandidate[], ignoreToolPrefixes: string[]): RecallCandidate[];
+/**
+ * Pure sync verbatim scan over candidates. No LLM, no IO, no index-engine.
+ * Per-message truncation to perMessageBudget; per-kind hit caps
+ * (maxMessageHits/maxSummaryHits/maxArtifactHits); total output capped
+ * by maxChars at render time.
+ */
+export declare function recall(entries: (MemoryEntry | RecallCandidate)[], query: string, options?: RecallOptions): RecallHit[];
+/** Render hits to context text, truncated verbatim to maxChars (default 900). */
+export declare function renderRecallContext(hits: RecallHit[], scope: RecallScope, maxChars?: number): string;

package/dist/features/session-memory/retention.d.ts

@@ -0,0 +1,29 @@
+import type { MemoryEntry } from "./types";
+export interface RetentionPolicy {
+    staleSessionDays?: number;
+    deletedSessionDays?: number;
+    orphanBlobDays?: number;
+}
+export interface RetentionReport {
+    stale: string[];
+    deleted: string[];
+    orphaned: string[];
+    skippedPinned: string[];
+}
+/** Cutoff timestamp: entries with updatedAt < cutoff are expired. */
+export declare function retentionCutoff(days: number, now?: number): number;
+/**
+ * Dry-run retention scan. Pure — never mutates input.
+ * stale undefined = disabled (no-op). Pinned entries are always skipped.
+ */
+export declare function pruneReport(entries: MemoryEntry[], policy?: RetentionPolicy, now?: number): RetentionReport;
+export interface PruneResult {
+    entries: MemoryEntry[];
+    report: RetentionReport;
+}
+/**
+ * Apply retention as tombstones (never hard-delete). Pure — returns new array.
+ * deleted/orphan/stale matches get text redacted to [removed] / [pruned:id].
+ * Pinned entries are always skipped.
+ */
+export declare function prune(entries: MemoryEntry[], policy?: RetentionPolicy, now?: number): PruneResult;

package/dist/features/session-memory/storage.d.ts

@@ -0,0 +1,21 @@
+import { type MemoryEntry, type MemoryEntryInput } from "./types";
+export declare function getProjectMemoryDir(directory: string): string;
+export declare function getMemoryDir(directory?: string): string;
+export declare function getMemoryFilePath(directory?: string): string;
+export declare function writeJsonAtomic(filePath: string, data: unknown): void;
+export declare function acquireLock(dirPath: string): {
+    acquired: boolean;
+    release: () => void;
+};
+export declare function acquireLockWithRetry(dirPath: string, retries?: 4): Promise<{
+    acquired: boolean;
+    release: () => void;
+}>;
+export declare function generateMemoryId(): string;
+export declare function appendMemoryEntry(input: MemoryEntryInput, directory?: string): MemoryEntry | null;
+export declare function readMemoryEntries(directory?: string): MemoryEntry[];
+export interface ListMemoryOptions {
+    sessionId?: string;
+    includeRemoved?: boolean;
+}
+export declare function listMemoryEntries(options?: ListMemoryOptions, directory?: string): MemoryEntry[];

package/dist/features/session-memory/summary.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryEntry } from "./types";
+export interface SummarySource {
+    id: string;
+    sessionId: string;
+    messageId: string;
+    text: string;
+}
+export interface SummaryNode {
+    id: string;
+    sessionId: string;
+    messageId: string;
+    snippet: string;
+}
+export interface ShapeSummaryOptions {
+    perMessageBudget?: number;
+    compactContextLimit?: number;
+}
+/** Verbatim truncate — mirrors upstream truncate(), no text mutation beyond cut. */
+export declare function truncateSummary(text: string, limit: number): string;
+/**
+ * Pure deterministic verbatim shaper. No LLM, no IO, no index-engine.
+ * Sorts by (sessionId, messageId, id); truncates each message to
+ * perMessageBudget (default 110); total output capped at
+ * compactContextLimit (default 1200).
+ */
+export declare function shapeSummaryNodes(entries: (MemoryEntry | SummarySource)[], options?: ShapeSummaryOptions): SummaryNode[];

package/dist/features/session-memory/types.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export declare const MemoryScopeSchema: z.ZodEnum<{
+    project: "project";
+    global: "global";
+    session: "session";
+}>;
+export type MemoryScope = z.infer<typeof MemoryScopeSchema>;
+export declare const MemoryEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<{
+        project: "project";
+        global: "global";
+        session: "session";
+    }>>;
+    text: z.ZodString;
+    chars: z.ZodNumber;
+    tokens: z.ZodNumber;
+    pinned: z.ZodDefault<z.ZodBoolean>;
+    removed: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
+export declare const MemoryEntryInputSchema: z.ZodObject<{
+    scope: z.ZodDefault<z.ZodEnum<{
+        project: "project";
+        global: "global";
+        session: "session";
+    }>>;
+    pinned: z.ZodDefault<z.ZodBoolean>;
+    text: z.ZodString;
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    removed: z.ZodDefault<z.ZodBoolean>;
+    chars: z.ZodOptional<z.ZodNumber>;
+    tokens: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    updatedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MemoryEntryInput = z.infer<typeof MemoryEntryInputSchema>;

package/dist/features/session-state/state.d.ts

@@ -0,0 +1,34 @@
+export declare const subagentSessions: Set<string>;
+export declare function registerSubagentSession(sessionID: string, parentSessionID: string): void;
+export declare function unregisterSubagentSession(sessionID: string): void;
+export declare function getParentSessionID(subagentSessionID: string): string | undefined;
+/**
+ * Live subagent session IDs registered under the given parent session.
+ * Only sessions still present in `subagentSessions` (i.e. not yet
+ * unregistered on task end) are returned.
+ */
+export declare function getSubagentSessionIDs(parentSessionID: string): string[];
+export declare function setMainSession(id: string | undefined): void;
+export declare function getMainSessionID(): string | undefined;
+/**
+ * Whether a session.created payload should be tracked as the plugin's main
+ * session. Top-level sessions (no parentID) qualify UNLESS they are internal
+ * sessions of another plugin (e.g. opencode-mem structured-output capture
+ * sessions are top-level with metadata["opencode-mem"].internal === true).
+ * Foreign top-level sessions must not hijack main-session tracking.
+ */
+export declare function isMainSessionCandidate(sessionInfo: {
+    id?: string;
+    parentID?: string;
+    metadata?: Record<string, unknown>;
+} | undefined): boolean;
+/** @internal For testing only */
+export declare function _resetForTesting(): void;
+export declare function setSessionAgent(sessionID: string, agent: string): void;
+export declare function updateSessionAgent(sessionID: string, agent: string): void;
+export declare function getSessionAgent(sessionID: string): string | undefined;
+export declare function clearSessionAgent(sessionID: string): void;
+export declare function setSessionModel(sessionID: string, model: string): void;
+export declare function getSessionModel(sessionID: string): string | undefined;
+export declare function clearSessionModel(sessionID: string): void;
+export declare function releaseSubagentSession(sessionID: string): void;

package/dist/features/task-session-scope/ancestry.d.ts

@@ -0,0 +1,23 @@
+import type { Task } from "../task-storage/types";
+/**
+ * Maximum parentID hops followed from a candidate to an in-scope ancestor.
+ * Mirrors `MAX_PARENT_DEPTH = 3` in `task-link.ts`: candidate → parent (1) →
+ * grandparent (2) → great-grandparent (3). A task at hop 4 or beyond is not included.
+ */
+export declare const DEFAULT_ANCESTRY_DEPTH = 3;
+export interface AncestryOptions {
+    /** Directory holding the `T-*.json` store; parents are resolved inside it only. */
+    taskDir: string;
+    /** Max parentID hops. Defaults to {@link DEFAULT_ANCESTRY_DEPTH}. */
+    depth?: number;
+}
+/**
+ * Expand an in-scope task set with every candidate whose `parentID` chain reaches it.
+ *
+ * Returns `scoped` plus the newly admitted candidates, preserving input order. The
+ * walk is one pass over the candidates against the *original* in-scope set, so it
+ * cannot run away: adding a candidate never creates a new root that a later candidate
+ * could hang off. Two candidates chained to each other (both foreign) are therefore
+ * both excluded — correct, since neither is anchored to this session.
+ */
+export declare function expandByParentAncestry(scoped: Task[], candidates: Task[], opts: AncestryOptions): Task[];

package/dist/features/task-session-scope/index.d.ts

@@ -0,0 +1,2 @@
+export { type AncestryOptions, DEFAULT_ANCESTRY_DEPTH, expandByParentAncestry } from "./ancestry";
+export { hasIncompleteTasksForSession, readSessionTasks, type SessionTaskQuery, } from "./session-task-pending";

package/dist/features/task-session-scope/session-task-pending.d.ts

@@ -0,0 +1,83 @@
+import type { MatrixxConfig } from "../../config/schema";
+import type { Task } from "../task-storage/types";
+export interface SessionTaskQuery {
+    /** Plugin config; only the `tasks.*` storage/staleness keys are consulted. */
+    config?: Partial<MatrixxConfig>;
+    /** Project directory — the task store is resolved from it. */
+    directory: string;
+    /** The session whose pending work is being asked about. */
+    sessionID: string;
+    /** Explicit subagent session ids to include in the scope. */
+    subagentIDs?: string[];
+    /**
+     * Drop tasks whose file has had no write activity past the stale threshold.
+     * Defaults to true so a worker that died cannot leak a pending handle forever.
+     */
+    excludeStale?: boolean;
+    /**
+     * Max `parentID` hops followed upward when admitting delegated workers' tasks.
+     * Defaults to 3 (`DEFAULT_ANCESTRY_DEPTH`), matching `MAX_PARENT_DEPTH` in
+     * `src/hooks/plan-persister/task-link.ts`. Deeper chains stay out of scope, which
+     * under-counts rather than over-counts — the safe direction for a completion gate.
+     */
+    ancestryDepth?: number;
+    /**
+     * Overrides the config-derived stale window (`tasks.stale_after_hours`, default 24h)
+     * for this query only. The background completion gates pass a much shorter window
+     * (`tasks.background_stale_after_hours`, default 2h) so a dead background handle is
+     * not held open for a full day, while the continuation enforcer keeps its 24h.
+     */
+    staleAfterMs?: number;
+}
+/**
+ * Read the file-backed task store (`.matrixx/tasks/T-{uuid}.json`) and return the
+ * tasks that belong to one specific session, i.e. the substrate that replaces the
+ * legacy OpenCode todo read.
+ *
+ * Fail-open contract: every failure mode resolves to "no pending work" — `[]` from
+ * {@link readSessionTasks}, `false` from {@link hasIncompleteTasksForSession}. A
+ * missing directory, an unparseable file, or an unexpected exception must never
+ * block completion of anything, because the predicate feeds completion gates where
+ * a stuck `true` is a livelock and a stuck `false` is a harmless lost nudge. Nothing
+ * here throws; the one wrapping `try`/`catch` always logs before returning.
+ *
+ * Strict scope: a task is kept only when its `threadID` is the queried session or
+ * one of the explicitly listed subagent ids. `tasks.session_scoped` is deliberately
+ * NOT read here — `src/config/schema/tasks.ts` scopes that key to the
+ * task-continuation-enforcer alone, and widening the scope of a completion gate to
+ * "every project task" is exactly the livelock this module exists to prevent.
+ * This intentionally diverges from `filterTasksBySession`, which stays lenient
+ * (unscoped opt-out plus pass-through for unattributed tasks) for the enforcer;
+ * the divergence is documented, not erased.
+ *
+ * `TaskObjectSchema.threadID` is required, so a task with no session attribution
+ * fails schema validation and is skipped by `readJsonSafe`. That is a feature: it
+ * makes unscoped tasks structurally invisible here, eliminating the "unscoped task
+ * blocks every session" vector.
+ *
+ * The direct filter above is not the whole scope. Work delegated to a subagent (or a
+ * grandchild) is recorded under the *worker's* `threadID`, so the strict match alone
+ * would let a parent complete while its own delegated work is still open. The kept
+ * set is therefore expanded upward along the on-disk `parentID` chain by
+ * `expandByParentAncestry` — see `./ancestry.ts` for the depth bound, the cycle rule,
+ * and why that backstop is durable where the in-memory `subagentSessions` registry is
+ * not. `subagentIDs` stays: the union is the correct scope, since the registry still
+ * adds coverage while the process is alive.
+ *
+ * Staleness uses the real exports `getStaleAfterMs` / `isTaskStale` from the
+ * enforcer's `staleness.ts` (their names are unchanged; only this call site is new).
+ */
+export declare function readSessionTasks(query: SessionTaskQuery): Task[];
+/**
+ * Does this session still have pending work in the file-backed task store?
+ *
+ * Equivalent to `getIncompleteTasks(readSessionTasks(query)).length > 0`.
+ * Fails open — see the fail-open contract on {@link readSessionTasks}.
+ *
+ * `dropSubtasksWithResolvedParent` is intentionally NOT applied. Counting a
+ * subtask whose parent is already resolved only over-counts, which keeps the
+ * agent working a little longer; dropping it under-counts, which is the direction
+ * that lets unfinished work go unnoticed. For a completion gate the safe error is
+ * the conservative one.
+ */
+export declare function hasIncompleteTasksForSession(query: SessionTaskQuery): boolean;

package/dist/features/task-storage/storage.d.ts

@@ -0,0 +1,23 @@
+import type { z } from "zod";
+import type { MatrixxConfig } from "../../config/schema";
+export declare function getProjectTaskDir(directory: string): string;
+export declare function getTaskDir(config?: Partial<MatrixxConfig>, directory?: string): string;
+export declare function sanitizePathSegment(value: string): string;
+export declare function resolveTaskListId(config?: Partial<MatrixxConfig>): string;
+export declare function readJsonSafe<T>(filePath: string, schema: z.ZodType<T>): T | null;
+export declare function writeJsonAtomic(filePath: string, data: unknown): void;
+export declare function acquireLockWithRetry(dirPath: string, retries?: number): Promise<{
+    acquired: boolean;
+    release: () => void;
+}>;
+export declare function generateTaskId(): string;
+export declare function listTaskFiles(config?: Partial<MatrixxConfig>, directory?: string): string[];
+export declare function migrateLegacyTasksIfNeeded(config: Partial<MatrixxConfig>, directory: string): {
+    migrated: number;
+    legacyDir: string;
+    projectDir: string;
+};
+export declare function acquireLock(dirPath: string): {
+    acquired: boolean;
+    release: () => void;
+};