opencode-swarm 7.189.0 → 7.190.0

package/dist/epic/plan-key.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Plan identity for Epic commits (Epic v2 C0, reshaped in C3).
+ *
+ * Every commit Epic writes for a task — the worktree LANDING merge commit of
+ * its coder and the RESIDUE commit of a non-coder writer (test_engineer,
+ * docs, …) — has the subject `swarm(task <id>): …` and a final
+ * `Swarm-Plan: <planKey>` trailer, where
+ * `planKey = sha256(planIdentityHash + '|' + (planEpoch ?? '')).slice(0, 16)`.
+ * The plan epoch is minted per ledger root, so two consecutive plans with the
+ * same title (every plan has a `1.1`) get different keys. Task ids repeat
+ * across plans, so a commit is attributed to a task only when its trailer
+ * names the current plan.
+ *
+ * Predecessor evidence no longer greps history: wave close records each
+ * task's commit in the epic record and mirrors it to the ref
+ * `refs/swarm/epics/<epicKey>/tasks/<id>` (`markers.ts`). The marker
+ * subject + trailer remain the way wave close and `/swarm epic status
+ * --repair-refs` find a task's commit inside the epic's own commit range.
+ *
+ * Records are NUL-separated (`git log -z`); git refuses NUL bytes in commit
+ * messages, so a message body cannot forge a record boundary.
+ *
+ * Subprocess discipline: no git call is made here; readers go through
+ * `src/git/branch.ts` `gitExec` (AGENTS.md #3).
+ */
+import type { Plan } from '../config/plan-schema.js';
+import { readLedgerEvents as readLedgerEvents_import, readPlanEpochIdentity as readPlanEpochIdentity_import } from '../plan/ledger.js';
+/** The commit-message trailer key binding a marker to its plan. */
+export declare const SWARM_PLAN_TRAILER_KEY = "Swarm-Plan";
+/** Identity of the plan whose markers may be honored. */
+export interface PlanMarkerScope {
+    /** 16-hex-char key written into the `Swarm-Plan:` trailer. */
+    planKey: string;
+    /**
+     * Earliest plan-ledger event time (ms since epoch), or null when the
+     * ledger is absent / carries no parseable timestamp.
+     */
+    rootTimestampMs: number | null;
+}
+/** One `swarm(task <id>):` commit read back from git. */
+export interface ParsedTaskMarker {
+    /** Full commit id (`%H`). */
+    sha: string;
+    taskId: string;
+    /** Last `Swarm-Plan:` trailer value; null when the commit carries none. */
+    planKey: string | null;
+}
+/** Subject shape produced by {@link formatEpicTaskCommitMessage}. */
+export declare const SWARM_TASK_SUBJECT_RE: RegExp;
+/**
+ * `git log -z --format` producing `<sha> US <raw message>` per commit,
+ * records separated by NUL (`-z`).
+ */
+export declare const MARKER_LOG_FORMAT = "--format=%H%x1f%B";
+/** Bound on scope resolution (ledger reads) so status never hangs. */
+export declare const PLAN_SCOPE_RESOLVE_TIMEOUT_MS = 10000;
+/** Max (directory, planKey) entries in the root-timestamp cache (FIFO). */
+export declare const MAX_ROOT_TS_CACHE_ENTRIES = 16;
+/**
+ * Defensive taskId scrubber for commit-subject and grep-pattern use (Phase
+ * 17 C.H2). Plan-ledger dep ids flow here from LLM-authored plans without
+ * re-validation; a `)` or newline would corrupt the subject regex. Keeps
+ * only characters safe in both a git subject and an ERE literal.
+ */
+export declare function scrubTaskIdForGitSubject(taskId: string): string;
+/** `sha256(planIdentityHash + '|' + (planEpoch ?? '')).slice(0, 16)`. */
+export declare function computePlanKey(planIdentityHash: string, planEpoch: string | null): string;
+/** The trailer line closing every Epic task commit message. */
+export declare function formatSwarmPlanTrailer(planKey: string): string;
+/**
+ * The message of an Epic task commit (landing merge or residue): subject
+ * `swarm(task <id>): <summary>` — the summary whitespace-collapsed and
+ * truncated to keep the subject within git's conventional 72 columns — and a
+ * final `Swarm-Plan: <planKey>` trailer. The task id is scrubbed by
+ * {@link scrubTaskIdForGitSubject}. Treat the shape as a stable contract.
+ */
+export declare function formatEpicTaskCommitMessage(taskId: string, planKey: string, summary?: string): string;
+/**
+ * Resolve the plan scope (planKey + plan root time) for `plan` — used by
+ * `/swarm epic status` to date recorded merge failures. Throws when the
+ * ledger identity is invalid/conflicting or the read exceeds
+ * {@link PLAN_SCOPE_RESOLVE_TIMEOUT_MS}; the caller then reports the root as
+ * unknown (every failure blocking).
+ */
+export declare function resolvePlanMarkerScope(directory: string, plan: Plan): Promise<PlanMarkerScope>;
+/**
+ * Parse `git log -z` output produced with {@link MARKER_LOG_FORMAT}. Records
+ * whose subject is not a `swarm(task <id>):` marker are dropped (a squash
+ * message may quote a marker in its body).
+ */
+export declare function parseTaskMarkerLog(output: string): ParsedTaskMarker[];
+/** Test-only: number of cached root timestamps. */
+export declare function _rootTimestampCacheSizeForTest(): number;
+/** Test-only: clear the root-timestamp cache. */
+export declare function _resetRootTimestampCacheForTest(): void;
+/**
+ * DI seam (AGENTS.md invariant 7) — tests substitute ledger readers and the
+ * resolution deadline without `mock.module`. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    readLedgerEvents: typeof readLedgerEvents_import;
+    readPlanEpochIdentity: typeof readPlanEpochIdentity_import;
+    resolveTimeoutMs: number;
+};

package/dist/epic/plan-shaping-seam.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Epic v2 C7 — the `save_plan` plan-shaping seam (Epic side).
+ *
+ * `save_plan` calls {@link computeSavePlanEpicShaping} ONLY when the config
+ * it already loaded has `epic.mode.enabled === true`, AFTER the plan
+ * lock is released, inside its own try/catch (a throw ⇒ the save still
+ * succeeds, without `epic_shaping`). With Epic off nothing here runs: no
+ * config read, no I/O, no await (the seam is in `src/tools/save-plan.ts`).
+ *
+ * What it does (Epic on):
+ *   - nothing while an epic is open for the project: shaping is pre-start
+ *     advice; a plan revised mid-epic (e.g. fix tasks) is planned by
+ *     `epic_next_wave`;
+ *   - inputs as `/swarm epic start` sizes the plan: live declared scopes,
+ *     learned signals from the project prior, the wave width
+ *     (`max_parallel_coders` in a git project, 1 otherwise — detected by a
+ *     `.git` entry in the project root or an ancestor, no git subprocess),
+ *     and co-change from the WARM in-memory cache only
+ *     (`peekCoChangeData`; no git scan on a plan save). Cold ⇒ path-only,
+ *     flagged `cochange: 'cold'` (r2 critic MINOR 12: the cache is filled by
+ *     `/swarm epic start`, `/swarm coupling` and `epic_next_wave`, so a
+ *     save_plan before any of them shapes path-only);
+ *   - `shapeEpicPlan` (pure, bounded by its budget);
+ *   - an iteration counter per plan identity in `.swarm/epic/shaping.json`
+ *     (a different plan restarts at 1); from iteration
+ *     {@link SHAPING_ACCEPT_ITERATION} the next step says to accept the plan
+ *     and proceed rather than reshape again.
+ *
+ * Result (`SavePlanResult.epic_shaping`): a one-line advisory when the plan
+ * is not epic-sized and no suggestion fixes that (r2 critic M5 — "run it in
+ * Balanced") or when it is over the shaping budget; otherwise the full
+ * advisory with ranked suggestions, a `next_step` and the iteration.
+ */
+import type { Plan } from '../config/plan-schema.js';
+import type { PluginConfig } from '../config/schema.js';
+import { loadPlanJsonOnly } from '../plan/manager.js';
+import { peekCoChangeData } from './cochange-source.js';
+import { resolveEpicDeclaredScopes } from './declared-scopes.js';
+import { loadEpicLearningView } from './learning-store.js';
+import { isEpicOpenForProject } from './lifecycle.js';
+import { type EpicShapingReport, shapeEpicPlan } from './shaping.js';
+import type { EpicShapingSuggestion } from './shaping-suggestions.js';
+/** `.swarm/epic/shaping.json` — the iteration counter. */
+export declare const EPIC_SHAPING_RELATIVE_PATH: string;
+/** From this iteration on, `next_step` says accept and proceed. */
+export declare const SHAPING_ACCEPT_ITERATION = 3;
+export type EpicShapingCochangeState = 'warm' | 'cold' | 'disabled';
+/**
+ * One suggestion as `save_plan` reports it: the shaping suggestion with
+ * every key in snake_case (`task_ids`, `file_kind`, `edge_share`,
+ * `patch.new_task`, `patch.edits[].task_id`, …), its ΔS_eff as
+ * `delta_effective_speedup` and the what-if as `what_if`.
+ */
+export type EpicShapingAdvisorySuggestion = {
+    type: EpicShapingSuggestion['type'];
+    summary: string;
+    delta_effective_speedup: number | null;
+    what_if: {
+        effective_speedup: number;
+        epic_sized: boolean;
+    } | null;
+} & Record<string, unknown>;
+export interface EpicShapingAdvisory {
+    status: 'acceptable' | 'improvable';
+    epic_sized: boolean;
+    effective_speedup: number;
+    pending_tasks: number;
+    serial_steps: number;
+    /** Sizing reasons (empty when epic-sized). */
+    reasons: string[];
+    cochange: EpicShapingCochangeState;
+    suggestions: EpicShapingAdvisorySuggestion[];
+    iteration: number;
+    next_step: string;
+}
+/** `SavePlanResult.epic_shaping`. */
+export type EpicSavePlanShaping = {
+    status: 'not-epic-sized';
+    message: string;
+    cochange: EpicShapingCochangeState;
+} | {
+    status: 'skipped-budget';
+    message: string;
+    cochange: EpicShapingCochangeState;
+} | EpicShapingAdvisory;
+/**
+ * Count this save as one shaping iteration of the plan (identity hash +
+ * ledger root ⇒ a new plan or a re-rooted ledger restarts at 1). A write
+ * failure is logged; the advisory still carries the computed iteration.
+ */
+export declare function bumpShapingIteration(directory: string, plan: Plan): number;
+/** The `epic_shaping` value of one shaping report. */
+export declare function toSavePlanShaping(report: EpicShapingReport, iteration: number, cochange: EpicShapingCochangeState): EpicSavePlanShaping;
+/**
+ * The `epic_shaping` of a saved plan, or null when an epic is open. The
+ * caller has checked the Epic config gate; may throw (the caller fails
+ * open). Shapes the PERSISTED plan (`plan.json` as save_plan just wrote it
+ * — statuses preserved, current_phase normalized), falling back to the
+ * plan the caller saved when it cannot be read.
+ */
+export declare function computeSavePlanEpicShaping(directory: string, savedArgsPlan: Plan, config: PluginConfig): Promise<EpicSavePlanShaping | null>;
+/** Test-only DI seam (AGENTS.md invariant 7). */
+export declare const _internals: {
+    isEpicOpenForProject: typeof isEpicOpenForProject;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly;
+    peekCoChangeData: typeof peekCoChangeData;
+    loadEpicLearningView: typeof loadEpicLearningView;
+    resolveEpicDeclaredScopes: typeof resolveEpicDeclaredScopes;
+    shapeEpicPlan: typeof shapeEpicPlan;
+    existsSync: (target: string) => boolean;
+    now: () => number;
+};

package/dist/epic/planning-signals.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Epic v2 C5/C6 — the planner's inputs beyond the plan, read ONCE per
+ * planning call by both callers of the component planner (`epic_next_wave`
+ * and the `/swarm epic start` sizing dry-run) so the two plan with the same
+ * signals:
+ *
+ *   - learned signals (`learning.ts`) when `epic.learning.enabled` is
+ *     not false: the hot files (tasks declaring one run alone) and the
+ *     co-write weights that expand each task's scope in the conflict graph.
+ *     Read from the open epic's posterior (`epic_next_wave`), else from the
+ *     project prior (the start's sizing, before the epic exists);
+ *   - co-change: the git co-change pairs + threshold when
+ *     `epic.cochange.enabled` (null otherwise ⇒ path-only conflicts);
+ *   - density threshold: the static `epic.mode.activation_threshold`
+ *     — the intra-component density above which a component runs serially.
+ *
+ * A failed read degrades to "no signal" (no learned signal / path-only),
+ * the fail-open the planner always had for these optional signals; the
+ * wave verdict still guards every issued wave. The sources are injected so
+ * each caller keeps its own `_internals` DI seam.
+ */
+import type { PluginConfig } from '../config/schema.js';
+import type { CoChangeData } from './cochange-source.js';
+import { type EpicCochangeSignal } from './components.js';
+import { type EpicCoWriteIndex, type EpicLearningSettings } from './learning.js';
+import type { EpicIdentity, EpicLearningView } from './learning-store.js';
+export interface EpicPlanningSignals {
+    hotFiles: string[];
+    coWrites: EpicCoWriteIndex | null;
+    cochange: EpicCochangeSignal | null;
+    densityThreshold: number;
+}
+export interface EpicPlanningSignalSources {
+    loadLearningView: (directory: string, epic: EpicIdentity | null, settings: EpicLearningSettings, nowMs: number) => EpicLearningView;
+    getCoChangeData: (directory: string) => Promise<CoChangeData>;
+    now: () => number;
+}
+export declare function loadEpicPlanningSignals(directory: string, config: Pick<PluginConfig, 'turbo' | 'epic'>, sources: EpicPlanningSignalSources, epic: EpicIdentity | null): Promise<EpicPlanningSignals>;

package/dist/epic/report.d.ts

@@ -0,0 +1,152 @@
+/**
+ * `/swarm epic report [<key>|last] [--format json]` (Epic v2 C8): the
+ * scorecard (`scorecard.ts`) of the open epic, computed live from its
+ * record, or of a past epic, read from its close report in
+ * `.swarm/epic-prior/reports/` (kept across `/swarm close`, newest 50).
+ *
+ * Selection: no selector ⇒ the open epic when one is open, else the newest
+ * report; `last` ⇒ the newest report; `<key>` ⇒ the report `<key>.json`
+ * (a report key) or the newest report of epic `<key>` (an epic key).
+ * "Newest" is by file mtime (as the 50-report pruning), then name.
+ *
+ * Strict reader: a report is read only when it is an `epic-report-v2`
+ * report whose embedded scorecard validates group by group (every field the
+ * formatter reads, {@link EpicScorecardSchema}); anything else is reported
+ * as unreadable, never half-rendered.
+ *
+ * Read-only and bounded: one directory listing, `stat` per report, and one
+ * report read (≤ {@link MAX_EPIC_REPORT_BYTES}); the live view is sentinel
+ * first (no sentinel ⇒ no DB open). Like `/swarm epic status` it works
+ * regardless of the Epic config gate and for an orphaned epic (both noted).
+ */
+import { z } from 'zod';
+import { loadPlanJsonOnly } from '../plan/manager.js';
+import { type EpicLearningSettings } from './learning.js';
+import { loadEpicLearningView } from './learning-store.js';
+import { type EpicRecordV1, epicSentinelExists, inspectEpic } from './lifecycle.js';
+import { completedBeforeEpic } from './next-wave.js';
+import { type EpicScorecardV1 } from './scorecard.js';
+/** Largest close report read (reports are bounded by the record). */
+export declare const MAX_EPIC_REPORT_BYTES: number;
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    epicSentinelExists: typeof epicSentinelExists;
+    inspectEpic: typeof inspectEpic;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly;
+    completedBeforeEpic: typeof completedBeforeEpic;
+    loadEpicLearningView: typeof loadEpicLearningView;
+    now: () => number;
+};
+export type EpicReportSelection = {
+    status: 'ok';
+    source: 'live' | 'report';
+    /** Null for the live scorecard. */
+    reportKey: string | null;
+    scorecard: EpicScorecardV1;
+    /** Caveats shown with a live scorecard (orphaned, config off). */
+    notes?: string[];
+} | {
+    status: 'none';
+    message: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Report file names in `.swarm/epic-prior/reports/`, newest first. */
+export declare function listEpicPriorReports(directory: string): string[];
+/**
+ * Every scorecard group the formatter and the JSON consumers read. Unknown
+ * keys are allowed (a newer writer may add fields); a missing or mistyped
+ * known field makes the report unreadable.
+ */
+export declare const EpicScorecardSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"epic-scorecard-v1">;
+    epicKey: z.ZodString;
+    planId: z.ZodString;
+    outcome: z.ZodEnum<{
+        completed: "completed";
+        open: "open";
+        abandoned: "abandoned";
+        "abandoned-by-swarm-close": "abandoned-by-swarm-close";
+    }>;
+    startedAt: z.ZodString;
+    closedAt: z.ZodNullable<z.ZodString>;
+    forced: z.ZodBoolean;
+    sizingAtStart: z.ZodObject<{
+        epicSized: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodString>;
+        pendingTasks: z.ZodNumber;
+        scopedTasks: z.ZodNumber;
+        scopeCoverage: z.ZodNumber;
+        serialSteps: z.ZodNumber;
+        concurrency: z.ZodNumber;
+        effectiveSpeedup: z.ZodNumber;
+    }, z.core.$strip>;
+    tasks: z.ZodObject<{
+        total: z.ZodNullable<z.ZodNumber>;
+        completedInEpic: z.ZodNumber;
+        adoptedAtStart: z.ZodOptional<z.ZodNumber>;
+        exclusive: z.ZodNumber;
+        serialComponent: z.ZodNumber;
+    }, z.core.$strip>;
+    waves: z.ZodObject<{
+        count: z.ZodNumber;
+        parallel: z.ZodNumber;
+        meanWidth: z.ZodNumber;
+        maxWidth: z.ZodNumber;
+    }, z.core.$strip>;
+    time: z.ZodObject<{
+        method: z.ZodLiteral<"wave-span-v1">;
+        label: z.ZodString;
+        spanMs: z.ZodNumber;
+        workMs: z.ZodNumber;
+        concurrencyFactor: z.ZodNullable<z.ZodNumber>;
+        interWaveIdleMs: z.ZodNumber;
+    }, z.core.$strip>;
+    conflicts: z.ZodObject<{
+        mergeFailures: z.ZodNumber;
+        undeclaredWriteTasks: z.ZodNumber;
+        undeclaredFiles: z.ZodArray<z.ZodString>;
+        undeclaredFilesTotal: z.ZodNumber;
+    }, z.core.$strip>;
+    rework: z.ZodObject<{
+        tasksWithRework: z.ZodNumber;
+        extraGenerations: z.ZodNumber;
+        reopened: z.ZodNumber;
+    }, z.core.$strip>;
+    gates: z.ZodObject<{
+        stageAFirstPass: z.ZodObject<{
+            passed: z.ZodNumber;
+            of: z.ZodNumber;
+            rate: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        stageBFirstPass: z.ZodObject<{
+            passed: z.ZodNumber;
+            of: z.ZodNumber;
+            rate: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        phaseReviewFirstPass: z.ZodObject<{
+            passed: z.ZodNumber;
+            of: z.ZodNumber;
+            rate: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        boundedHistory: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    learning: z.ZodObject<{
+        priorDigest: z.ZodNullable<z.ZodString>;
+        topHotFiles: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * The scorecard of a parsed close report, or an error naming the first
+ * problem (wrong schema, or the scorecard field that failed validation).
+ */
+export declare function scorecardFromReport(raw: unknown): {
+    scorecard: EpicScorecardV1;
+} | {
+    error: string;
+};
+/** The live scorecard of the epic record `epic` (open or closing). */
+export declare function liveEpicScorecard(directory: string, epic: EpicRecordV1, learning: EpicLearningSettings): Promise<EpicScorecardV1>;
+/** Resolve `selector` (null / `last` / a report or epic key). */
+export declare function selectEpicReport(directory: string, selector: string | null, learning: EpicLearningSettings): Promise<EpicReportSelection>;

package/dist/epic/residue-commit.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Epic v2 C3 (X1) — residue commits for non-coder writers.
+ *
+ * Coders of an open git epic are isolated in worktrees and their work lands
+ * as a commit (`task-landing.ts`). Other agents write in the MAIN tree: the
+ * test_engineer writes the task's tests, the docs agent writes docs, and so
+ * on. Left uncommitted, those files are invisible to a rework coder (its
+ * worktree is cut from HEAD) and collide with its landing. So:
+ *
+ *   - when a non-coder delegation for a task of the open epic returns —
+ *     a foreground Task (the delegation gate's after-hook) or a background
+ *     one (the completion observer) — {@link commitEpicResidueAfterDelegation}
+ *     commits the main-tree writes still uncommitted on the epic branch:
+ *     the returning agent's own recorded writes as
+ *     `swarm(task <id>): <agent> residue`, then the rest of the task's
+ *     attribution and frozen scope as `swarm(task <id>): residue` (no
+ *     agent is claimed for files it did not record), each with the plan's
+ *     `Swarm-Plan:` trailer. Files another still-running delegation has
+ *     recorded (the concurrent Stage B reviewer/test_engineer) are left
+ *     alone: they belong to that writer and may be half-written;
+ *   - `epic_next_wave` runs {@link commitTaskResidue} again for each task of
+ *     the closing wave (a missed after-hook, a failed attempt); before a new
+ *     wave the remaining dirty paths belong to no task
+ *     ({@link classifyDirtyBaseline}).
+ *
+ * Attribution of a path to a task: the task's declared scope in the CURRENT
+ * (or closing) wave — literal files or directories, never globs — its write
+ * attribution in any session of this project, or, for the after-hook, any
+ * write recorded on the delegated agent's own child session. Scopes of
+ * earlier waves never attribute anything (later edits there are the
+ * user's). Never `.swarm/` (at any depth), never git pathspec magic; staging
+ * and the commit use `:(literal)` pathspecs, and the commit is `--only` so
+ * anything else in the index stays out of it. Every residue write is
+ * serialized with worktree merge-backs (one writer of the primary index at
+ * a time), and a failed commit restores the touched index entries exactly
+ * (the user's own staged state included).
+ *
+ * Subprocess discipline (AGENTS.md #3): status is read through `gitExec`;
+ * `git add` / `git commit` (and the index restore after a failed commit) run ONCE
+ * each through `gitExecOnce`; the commit is non-interactive
+ * (`--no-verify`, `-c commit.gpgsign=false`, closed stdin, timeout).
+ * Fail-open: every failure is a critical warning — the after-hook must never
+ * break, and `epic_next_wave` turns a persistent failure into `git-failed`.
+ */
+import { getAgentSession as getAgentSession_import } from '../state.js';
+import { checkEpicBranch as checkEpicBranch_import } from './epic-branch.js';
+import { gitExecOnce } from './git-once.js';
+import { type EpicRecordV1, epicSentinelExists as epicSentinelExists_import, getOpenEpic as getOpenEpic_import, readPlanTaskRef as readPlanTaskRef_import } from './lifecycle.js';
+import { collectTaskAttribution as collectTaskAttribution_import } from './wave-close.js';
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    epicSentinelExists: typeof epicSentinelExists_import;
+    getOpenEpic: typeof getOpenEpic_import;
+    readPlanTaskRef: typeof readPlanTaskRef_import;
+    checkEpicBranch: typeof checkEpicBranch_import;
+    collectTaskAttribution: typeof collectTaskAttribution_import;
+    getAgentSession: typeof getAgentSession_import;
+    /** Every in-process agent session (id → state), for in-flight writers. */
+    listAgentSessions: () => MapIterator<[string, import("../state.js").AgentSessionState]>;
+    gitExec: (args: string[], cwd: string) => string;
+    gitExecOnce: typeof gitExecOnce;
+    /** One writer at a time in the primary checkout (merge-back queue). */
+    serializeWithMergeBacks: <T>(task: () => T | Promise<T>) => Promise<T>;
+    now: () => number;
+};
+/** True for a path inside a `.swarm/` directory at any depth. */
+export declare function isSwarmStatePath(file: string): boolean;
+/** One uncommitted path outside `.swarm/` (porcelain v1). */
+export interface DirtyEntry {
+    path: string;
+    untracked: boolean;
+    /**
+     * False when the change is fully staged already (worktree column blank):
+     * `git add` must skip it (a staged deletion no longer matches a pathspec).
+     */
+    needsAdd?: boolean;
+    /** Source path of a rename/copy record (its deletion is staged). */
+    origin?: string;
+}
+/**
+ * Uncommitted paths outside `.swarm/` (untracked files listed individually).
+ * Throws when git fails.
+ */
+export declare function listDirtyEntries(directory: string): DirtyEntry[];
+/** Result of one residue commit attempt. */
+export type ResidueCommitResult = {
+    status: 'nothing';
+} | {
+    status: 'committed';
+    sha: string | null;
+    files: string[];
+} | {
+    status: 'failed';
+    error: string;
+    files: string[];
+};
+/**
+ * Commit, as task `taskId`'s residue, the dirty paths that are among
+ * `candidates` (exact repo-relative paths) or covered by `scopes` (declared
+ * files or directories). `dirty` is the current status (read once by the
+ * caller). Rename sources follow their destination.
+ */
+export declare function commitTaskResidue(args: {
+    directory: string;
+    epic: EpicRecordV1;
+    taskId: string;
+    label: string;
+    candidates: Iterable<string>;
+    scopes?: readonly string[];
+    dirty: readonly DirtyEntry[];
+}): ResidueCommitResult;
+/**
+ * The frozen declared scope of `taskId` in the epic's CURRENT wave (the
+ * issued, active one), or `[]`. Scopes of earlier, closed waves never
+ * attribute a later write: the user's edits there are not a task's residue.
+ */
+export declare function declaredScopeOf(epic: EpicRecordV1, taskId: string): string[];
+/** What the delegation gate hands the after-hook seam. */
+export interface EpicResidueRequest {
+    directory: string;
+    /** Raw `subagent_type` of the returned Task delegation. */
+    agent: string;
+    sessionID: string | undefined;
+    /** Plan task id(s) the delegation served (lazy: Epic-only work). */
+    resolveTaskIds: () => Promise<string[]>;
+    /** The delegated agent's child session id(s) (lazy). */
+    childSessionIds: () => Promise<Array<string | null | undefined>>;
+}
+/**
+ * After-hook seam (delegation gate, Task `tool.execute.after`): commit the
+ * residue of a non-coder writer that served a task of the open git epic.
+ * One `existsSync` and nothing else when no epic is open. Never throws.
+ */
+export declare function commitEpicResidueAfterDelegation(request: EpicResidueRequest): Promise<void>;
+/** Dirty paths before a new wave, by what Epic does with them. */
+export interface DirtyBaselineClassification {
+    /** Tracked changes: block the next wave (`dirty-baseline`). */
+    unattributedTracked: string[];
+    /** Untracked files: advisory only. */
+    unattributedUntracked: string[];
+}
+/**
+ * Classify the dirty paths before a new wave (X1 `dirty-baseline`). Residue
+ * is only ever attributed to tasks of the CURRENT wave (the after-hook) or
+ * the closing wave (`epic_next_wave` commits it before the close), so when a
+ * new wave is about to be issued nothing dirty belongs to a task any more:
+ * a later edit under an earlier task's declared directory is the user's,
+ * never swept into that task's residue. Tracked changes block; untracked
+ * files are only reported.
+ */
+export declare function classifyDirtyBaseline(dirty: readonly DirtyEntry[]): DirtyBaselineClassification;