dsh-ssh-tui 0.6.4 → 0.7.0-rc.2

package/lib/types/line-diff.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Line-level diffing for the tool card, and the word-level emphasis inside a
+ * changed pair.
+ *
+ * The card used to print every old line as `-` and every new line as `+`: a
+ * one-line change in a hundred-line file produced two hundred rows, which is
+ * unreadable and hides the change it is trying to show. This module keeps the
+ * classic shape — common lines as context, changes as `-`/`+` pairs, unchanged
+ * stretches collapsed to a marker — and reports which characters inside a
+ * replaced pair actually changed so the renderer can emphasise them.
+ * @module dsh-ssh-tui/line-diff
+ */
+/** One line of the diff. */
+export interface DiffLine {
+    kind: 'same' | 'add' | 'del';
+    text: string;
+    /** 0-based index in the old text, for `same` and `del`. */
+    oldIndex?: number;
+    /** 0-based index in the new text, for `same` and `add`. */
+    newIndex?: number;
+}
+/** A run of lines with its context, and how many unchanged lines were skipped. */
+export interface DiffHunk {
+    /** Unchanged lines collapsed before this run; 0 for the first. */
+    omittedBefore: number;
+    lines: DiffLine[];
+}
+/** Two columns plus a gutter need this much room to be worth it. */
+export declare const SIDE_BY_SIDE_MIN_WIDTH = 100;
+/** The gutter between the two columns. */
+export declare const SIDE_BY_SIDE_GUTTER = " \u2502 ";
+/**
+ * Whether a diff should be shown side by side at this terminal width.
+ *
+ * Below the threshold the columns would be narrower than the code they hold,
+ * which turns every changed line into a wrapped mess — stacked reads better.
+ * @param width - the terminal width in cells.
+ * @returns the layout to use.
+ */
+export declare function diffLayout(width: number): 'side-by-side' | 'stacked';
+/** One row of a side-by-side rendering. */
+export interface SideBySideRow {
+    /** Marker plus text for the left column: `- old`, `  context`, or empty. */
+    left: string;
+    /** Marker plus text for the right column: `+ new`, `  context`, or empty. */
+    right: string;
+    /** Emphasis inside `left`, offsets into it. */
+    leftSpans: DiffSpan[];
+    /** Emphasis inside `right`, offsets into it. */
+    rightSpans: DiffSpan[];
+    /** Whether both columns carry the same line (context) rather than a change. */
+    context: boolean;
+}
+/**
+ * Pair a line diff into two columns.
+ *
+ * A removed line immediately followed by an added one is a replacement and
+ * shares a row, with the changed characters emphasised on each side; a lone
+ * removal or addition keeps its own row with the other column empty. Context
+ * rows carry the text on both sides so the eye can follow either column.
+ * @param lines - a diff, as {@link diffLines} returns it.
+ * @returns the rows, in order.
+ */
+export declare function sideBySideRows(lines: readonly DiffLine[]): SideBySideRow[];
+/** One emphasized range inside a line, in UTF-16 offsets. */
+export interface DiffSpan {
+    start: number;
+    end: number;
+}
+/** Split text into lines, treating an empty string as no lines. */
+export declare function splitLines(text: string): string[];
+/**
+ * Diff two texts line by line.
+ *
+ * Equal lines are `same`, lines only in the old text are `del`, only in the new
+ * are `add` — in the order a reader expects. A pair this module cannot afford
+ * (see {@link MAX_DIFF_LINES}) degrades to "all removed, then all added", which
+ * is what the card rendered before but is at least bounded.
+ * @param oldText - the previous content; empty for a new file.
+ * @param newText - the new content.
+ * @returns the diff, oldest first.
+ */
+export declare function diffLines(oldText: string, newText: string): DiffLine[];
+/**
+ * Group a diff into runs of change with `context` unchanged lines around them,
+ * reporting how many unchanged lines were left out between runs.
+ * @param lines - a diff, as {@link diffLines} returns it.
+ * @param context - unchanged lines to keep on each side of a change.
+ * @returns the runs, in order; a diff with no changes yields no runs.
+ */
+export declare function diffHunks(lines: readonly DiffLine[], context?: number): DiffHunk[];
+/**
+ * The characters that differ between two lines: the common prefix and suffix
+ * are trimmed away, and what is left is emphasised.
+ *
+ * Whole-line emphasis was the old behaviour and it reads as noise on a line that
+ * changed one identifier. Trimming is greedy and therefore approximate — it does
+ * not try to align moved words — but it is exact about the boundaries it does
+ * report: everything outside the spans really is identical.
+ * @param oldText - the removed line.
+ * @param newText - the added line.
+ * @returns one span list per side, possibly empty when they are equal.
+ */
+export declare function wordDiffSpans(oldText: string, newText: string): {
+    old: DiffSpan[];
+    new: DiffSpan[];
+};

package/lib/types/line-mode.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Line mode: one plain line per event, for screen readers, log capture, and
+ * terminals where a full-screen repaint is the wrong shape.
+ *
+ * The TUI normally paints a framed screen: absolute cursor addressing, an
+ * alternate screen buffer, only the rows that changed, and a spinner that
+ * redraws in place. None of that survives a pipe, a screen reader, or a
+ * recording — the same event can appear twice, out of order, or not at all.
+ * This module turns a transcript row into the lines a log would carry, and the
+ * caller appends them once, in order, and never repaints.
+ *
+ * Colour is deliberately absent: the caller may style a line, but the text has
+ * to stand on its own because that is the point of the mode.
+ * @module dsh-ssh-tui/line-mode
+ */
+import type { Row } from './transcript-types.js';
+/** Whether the environment asks for line mode. `1/true/on/yes` all count. */
+export declare function lineModeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The lines one row contributes to the log.
+ *
+ * A row with embedded newlines contributes several lines — the alternative is
+ * joining them, which corrupts a report's structure for the reader this mode
+ * exists for. Rows that only make sense on a screen (the logo, a transient
+ * reasoning buffer) contribute nothing rather than noise.
+ * @param row - the transcript row that was just pushed.
+ * @returns the lines to append, in order; empty when the row is screen-only.
+ */
+export declare function lineModeLines(row: Row): string[];
+/**
+ * What one row's lines look like once appended.
+ *
+ * A trailing newline per line, and nothing else: no carriage returns (they
+ * would overwrite the line just written on a terminal) and no escape sequences.
+ */
+export declare function appendRow(lines: readonly string[]): string;

package/lib/types/paint.d.ts

@@ -43,10 +43,34 @@ export type LinkQuality = 'local' | 'good' | 'ok' | 'slow' | 'poor' | 'unknown';
 export declare function linkQualityOf(kind: PaintLinkKind, rttMs: number | undefined): LinkQuality;
 /** How many filled signal pips: 4 local/fast, 3 ok, 2 slow, 1 poor, 0 unknown. */
 export declare function linkSignalPips(quality: LinkQuality): number;
+/**
+ * How many bytes one frame may carry before the rest waits for the next tick.
+ *
+ * A 100x30 full repaint costs about 3.7 kB, which on a 400ms link is a third of
+ * a second of serialization the user waits through before anything moves. The
+ * cadence already follows the measured RTT; the budget bounds what each of
+ * those ticks may spend, so a resize or a burst of streaming output degrades
+ * into a few ordered frames instead of one long freeze and a queue behind it.
+ */
+export declare const FRAME_BYTE_BUDGETS: Record<LinkQuality, number>;
+/** The per-frame byte budget for a link quality. */
+export declare function frameByteBudget(quality: LinkQuality): number;
+/**
+ * How many body lines an expanded card may show before it points at the
+ * overlay, by link quality.
+ *
+ * A measured slow link is the only case that truncates: there, every body line
+ * is bytes the user waits for, and the overlay is one key away (`Enter`). Fast
+ * and unmeasured links keep the behavior 0.3.9 settled on — an expanded body
+ * shows in full, or opens in the overlay when it cannot fit the workspace — so
+ * nothing changes for a local terminal or a link whose RTT could not be probed.
+ */
+export declare const TOOL_BODY_LINES_BY_QUALITY: Record<LinkQuality, number>;
+/** The body-line cap for a link quality; `Infinity` means "show it all". */
+export declare function toolBodyLineLimit(quality: LinkQuality): number;
 /** Compact footer chip: `SSH ●●●○ 90ms` — 1 pip red, 2 yellow, 3+ green. */
 export declare function formatLinkQualityChip(kind: PaintLinkKind, intervalMs: number, rttMs: number | undefined, probed: boolean, color?: boolean): string;
-/** One incremental paint as a single stdout write (one SSH packet when corked). */
-export declare function composePaintOutput(options: {
+export interface PaintOptions {
     width: number;
     height: number;
     paintRows: readonly string[];
@@ -59,7 +83,60 @@ export declare function composePaintOutput(options: {
     cursorColumn: number;
     /** Keep the cursor hidden (session picker). Default shows it on the input. */
     hideCursor?: boolean;
-}): string;
+}
+export interface PaintFrame {
+    /** The single stdout write for this frame. */
+    output: string;
+    /** Row indices actually written, ascending. Only these are now up to date. */
+    painted: number[];
+    /** Rows that needed a paint but did not fit the byte budget. */
+    deferred: number[];
+    /** Highest deferred row, to pass back as `from` on the next frame. */
+    resume: number | undefined;
+    /** Bytes this frame carried, for the ledger `/diag` and the tests read. */
+    bytes: number;
+}
+/**
+ * Which dirty rows to paint first when a byte budget applies.
+ *
+ * Rows at or below `from` were deferred by the previous frame and go first so
+ * they cannot starve; everything above is the tail the user is looking at,
+ * painted newest-row-first so the input area is current even when the budget
+ * runs out. Without a `from`, the order is simply tail-first.
+ * @param dirty - row indices that need a paint, ascending.
+ * @param from - highest row the previous frame deferred, if any.
+ * @returns indices in paint order.
+ */
+export declare function paintOrder(dirty: readonly number[], from?: number): number[];
+/**
+ * Compose one incremental paint, optionally bounded by a byte budget.
+ *
+ * Every row is addressed absolutely, so the paint order is free: with a budget
+ * the frame spends it on the tail first and reports what it could not reach, so
+ * the caller keeps those rows dirty instead of forgetting them.
+ * @param options - the frame to paint, plus the budget and resume point.
+ * @returns the write, what it covered, and what is left for the next tick.
+ */
+export declare function composePaintFrame(options: PaintOptions & {
+    maxBytes?: number;
+    from?: number;
+}): PaintFrame;
+/**
+ * The snapshot for the next frame: only the rows a frame painted become clean.
+ *
+ * A deferred row has to keep its previous content in the snapshot, or the next
+ * frame would compare it against itself, call it unchanged, and never paint it:
+ * the row would simply stay wrong. The array also keeps its old length while
+ * anything is owed, so the "row count changed" clear keeps firing until the
+ * frame is complete.
+ * @param previous - the snapshot the frame painted against.
+ * @param current - the rows the frame wanted to show.
+ * @param painted - indices the frame actually wrote.
+ * @returns the snapshot to hand to the next frame.
+ */
+export declare function advancePaintedRows(previous: readonly string[], current: readonly string[], painted: readonly number[]): string[];
+/** One incremental paint as a single stdout write (one SSH packet when corked). */
+export declare function composePaintOutput(options: PaintOptions): string;
 /** Whether `text` could still grow into a recognized escape sequence. */
 export declare function isEscapePrefix(text: string): boolean;
 /** Parse a Device Status Report cursor reply (`CSI row;col R`). */
@@ -92,5 +169,13 @@ export declare function findCursorPositionReply(text: string): {
 export declare function probeTerminalRttMs(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream, timeoutMs?: number, ssh?: boolean): Promise<number | undefined>;
 /** Sliding window of `windowSize` items that keeps `cursor` visible. */
 export declare function pickerWindowStart(cursor: number, total: number, windowSize?: number): number;
-/** Immediate first-frame chrome so a 2–3s Host boot is not a blank TTY. */
+/**
+ * Immediate first-frame chrome so a 2–3s Host boot is not a blank TTY.
+ *
+ * Line mode gets nothing: a splash enters the alternate screen and paints over
+ * itself, which is exactly what that mode exists to avoid — the log would open
+ * with screen control instead of the session's first event.
+ * @param message - what the launcher is waiting for.
+ * @param color - whether colour is allowed.
+ */
 export declare function writeBootSplash(message: string, color?: boolean): void;

package/lib/types/plan.d.ts

@@ -62,6 +62,13 @@ export declare function planDockNote(plan: {
 /** Compact per-status counts matching the web plan strip. */
 export declare function todoProgressLabel(todos: readonly PlanTodoItem[]): string;
 export declare function todoItemKind(status: PlanTodoItem['status']): DisplayKind;
+/**
+ * A Braille bar for the plan's completion, in the same family as the context
+ * ring: `⣿` filled, `⣀` empty, and the eight partial cells between them.
+ * @param todos - the list as the model last wrote it.
+ * @param cells - bar width in cells.
+ */
+export declare function todoProgressBar(todos: readonly PlanTodoItem[], cells?: number): string;
 export declare function planMarkdownFromArgs(value: unknown): string | undefined;
 /** First markdown heading of an exit_plan_mode plan body. */
 export declare function planTitleFromMarkdown(markdown: string): string | undefined;

package/lib/types/preset-authoring.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `/preset`: the terminal's authoring surface for agent presets.
+ *
+ * A preset is a directory — an id, a composition file, and optional display
+ * metadata — and the web client reaches the same four operations the plugin
+ * exposes to it: list, read, copy, delete. This module mirrors that surface and
+ * adds display-name/description edits, which are the one authoring write the
+ * upstream service does not offer; it stays pure so every refusal is testable
+ * without a host, and `tui.ts` performs the two calls that touch the disk.
+ *
+ * The rules are the upstream ones, re-stated here so a command refuses before
+ * it calls out:
+ *
+ * - only `user` presets are writable; a shipped preset is refused by the
+ *   service as well (`agent-preset/read-only`);
+ * - a copy never overwrites: the destination id must be free;
+ * - ids match `/^[a-z0-9][a-z0-9-]*$/`;
+ * - deleting the preset the session is running is refused here, even though the
+ *   service allows it — the running session would keep its composition while
+ *   every later launch falls back to the default.
+ * @module dsh-ssh-tui/preset-authoring
+ */
+import { type AgentPreset, type PresetMetadata } from '@deepseek-ai/dsh-agent-presets';
+/** The id shape discovery accepts; a directory that fails it is skipped. */
+export declare const PRESET_ID_PATTERN: RegExp;
+/** Whether an id would be discovered at all. */
+export declare function validatePresetId(id: string): boolean;
+/**
+ * The directory a preset owns.
+ *
+ * `AgentPreset.path` is the composition file the preset publishes, not the
+ * directory, so anything that writes beside it (display metadata) starts here.
+ * @param preset - a discovered preset.
+ * @returns the absolute preset directory.
+ */
+export declare function presetDirectory(preset: AgentPreset): string;
+export type PresetRefusalCode = 'invalid-id' | 'exists' | 'not-found' | 'read-only' | 'system' | 'running' | 'empty-metadata';
+export interface PresetRefusal {
+    error: PresetRefusalCode;
+    /** The id the refusal is about, when it names one. */
+    id?: string;
+    /** The name that collided, for `exists`. */
+    name?: string;
+}
+export interface PresetCopyPlan {
+    kind: 'copy';
+    from: string;
+    id: string;
+    name?: string;
+}
+export interface PresetMetadataPlan {
+    kind: 'metadata';
+    id: string;
+    directory: string;
+    /** The `preset.yml` document to write, already rendered by upstream. */
+    text: string;
+}
+export interface PresetDeletePlan {
+    kind: 'delete';
+    id: string;
+}
+export type PresetPlan = PresetCopyPlan | PresetMetadataPlan | PresetDeletePlan;
+export declare function isRefusal(value: PresetPlan | PresetRefusal): value is PresetRefusal;
+/** One composition row as `/preset show` renders it. */
+export interface PresetRowView {
+    entryId: string | null;
+    moduleName: string;
+    enabled: boolean | 'conditional';
+    condition?: string;
+}
+/** One preset's composition as `/preset show` renders it. */
+export interface PresetCompositionView {
+    id: string;
+    name?: string;
+    isDefault: boolean;
+    broken?: string;
+    rows: readonly PresetRowView[];
+}
+/**
+ * The authoring subset of the service, feature-detected rather than assumed:
+ * the plugin still supports 0.1.2-rc.1, whose `agentPresets` may predate
+ * `copy`, `remove`, `read`, and `compositionInventory`. A missing member turns
+ * into a clear message instead of a crash.
+ */
+export interface PresetAuthoringApi {
+    readonly authorable?: boolean;
+    copy?(from: string, id: string, name?: string): Promise<void>;
+    remove?(id: string): Promise<void>;
+    read?(id: string): Promise<string>;
+    compositionInventory?(): Promise<readonly PresetCompositionView[]>;
+}
+/**
+ * Plan a copy of an existing preset under a new id.
+ *
+ * Copy is the only way to create one (upstream has no create or rename), and it
+ * carries the whole directory — composition, display metadata, and any scripts
+ * a preset ships beside them.
+ * @param input - the roster, whether authoring is possible, and the request.
+ * @returns the call to make, or why it must be refused.
+ */
+export declare function planCopy(input: {
+    presets: readonly AgentPreset[];
+    authorable: boolean;
+    from: string;
+    id: string;
+    name?: string | undefined;
+}): PresetCopyPlan | PresetRefusal;
+/**
+ * Plan a display-metadata edit (name, description, or both).
+ *
+ * The current document is merged, so editing one field never drops the other,
+ * and `order` survives. A shipped preset cannot be edited: its directory is
+ * read-only by definition.
+ * @param input - the preset, its current metadata, and the fields to change.
+ * @returns the file to write, or why it must be refused.
+ */
+export declare function planMetadata(input: {
+    preset: AgentPreset;
+    current: PresetMetadata;
+    patch: {
+        name?: string | undefined;
+        description?: string | undefined;
+    };
+}): PresetMetadataPlan | PresetRefusal;
+/**
+ * Plan a deletion.
+ * @param input - the preset, whether authoring is possible, and which preset
+ *   this session is running.
+ * @returns the call to make, or why it must be refused.
+ */
+export declare function planDelete(input: {
+    preset: AgentPreset;
+    authorable: boolean;
+    current: boolean;
+}): PresetDeletePlan | PresetRefusal;

package/lib/types/preset-picker.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The `/mode` picker's list: which presets to show, in what order, and what to
+ * say about each one.
+ *
+ * The dialog is a flat list of options, so the grouping a browser surface can
+ * draw is carried in three cheap ways: the groups are ordered (shipped first,
+ * then authored locally), every description names its group, and a preset that
+ * declares a position shows it. Nothing here touches the filesystem or the
+ * service — the caller passes what `list()` returned.
+ * @module dsh-ssh-tui/preset-picker
+ */
+import type { AgentPreset } from '@deepseek-ai/dsh-agent-presets';
+/** One option as the question dialog wants it, plus the id it stands for. */
+export interface PresetPickerOption {
+    id: string;
+    label: string;
+    description: string;
+    /** Why this preset cannot run, carried so the dialog can refuse it on pick. */
+    broken?: string;
+    /**
+     * Every name this preset answers to: the id, and the name it published even
+     * when the display label resolves elsewhere. `/mode <name>` matched a
+     * published name before the list was grouped, and dropping that would break
+     * a script that uses one.
+     */
+    aliases: string[];
+}
+/** The shipped presets, then the locally authored ones. */
+export interface PresetPickerGroup {
+    trust: 'system' | 'user';
+    title: string;
+    options: PresetPickerOption[];
+}
+/**
+ * Within a group: a declared position first, in ascending order, then the rest
+ * by id. `order` is the preset's own statement about where it belongs, so a
+ * deployment's curated sequence survives discovery.
+ */
+export declare function comparePresets(left: AgentPreset, right: AgentPreset): number;
+/**
+ * What one preset's line says underneath its name: where it sits, what it is
+ * for, and why it cannot run — in that order, because a broken preset's reason
+ * is the only thing the reader needs.
+ */
+export declare function presetOptionDescription(preset: AgentPreset, currentId: string): string;
+/** One option's label: the name the roster publishes, never empty. */
+export declare function presetOptionLabel(preset: AgentPreset): string;
+/**
+ * Group and order the roster for the picker.
+ * @param presets - what the service listed.
+ * @param currentId - the preset in effect, marked in each description.
+ * @returns shipped presets first, then authored ones; empty groups are omitted.
+ */
+export declare function groupPresets(presets: readonly AgentPreset[], currentId: string): PresetPickerGroup[];
+/** The same list, flattened the way the dialog takes it. */
+export declare function flattenGroups(groups: readonly PresetPickerGroup[]): PresetPickerOption[];
+/** Whether a preset answers to the name a caller typed. */
+export declare function optionMatches(option: PresetPickerOption, query: string): boolean;
+/**
+ * Narrow the roster to what a typed query matches: the id, the published name,
+ * and the description, case-insensitively. An empty query keeps everything, so
+ * the picker opens on the full roster.
+ */
+export declare function filterPresets(presets: readonly AgentPreset[], query: string): AgentPreset[];

package/lib/types/preset-rows.d.ts

@@ -1,5 +1,6 @@
 /**
- * The profile patch that mounts the agent-preset roster `/mode` needs.
+ * The profile patch that mounts the agent-preset roster `/mode` needs, plus the
+ * repair planner `/doctor` uses to fix a profile patch.
  *
  * A terminal profile built on `dsh-base` composes no preset roster (only the
  * Web bundle does), and this plugin's own bundle patch may not mount one: DSH
@@ -12,27 +13,116 @@
  * The roster is not cosmetic: without it `/mode` cannot switch, and the tools
  * the shipped presets own (`ask_user_question`, `present`, PTC's presentation)
  * are absent from the agent's catalog.
+ *
+ * Everything in this module is either a pure text function or a file write that
+ * takes a backup first: `/doctor` may repair a user's profile patch, and that
+ * must never lose the previous content or touch a row the user wrote.
  * @module dsh-ssh-tui/preset-rows
  */
+/** One host row the roster block mounts. */
+export interface RosterRow {
+    id: string;
+    name: string;
+    /** Lines below `config:`, written one level deeper than `config:`. */
+    config?: readonly string[];
+}
+/**
+ * The rows the terminal profile has to mount itself: the roster `/mode` lists,
+ * the TypeScript runtime the PTC preset needs, and the host-owned subagent
+ * delegation setting.
+ */
+export declare const ROSTER_ROWS: readonly RosterRow[];
+/** The comment header the block introduces itself with, in both writers. */
+export declare const ROSTER_PATCH_HEADER = "# dsh-ssh-tui /mode: the agent-preset roster (standard / minimal / PTC /\n# cordis, plus every preset under $DSH_HOME/.agent-presets) and the two host\n# services the shipped presets need. dsh-base composes no roster in a terminal\n# profile, and a third-party bundle patch may not mount an @deepseek-ai row, so\n# the profile's user layer owns them.\n";
+/** One top-level `- insert:` entry mounting exactly these rows. */
+export declare function rosterInsertEntry(rows: readonly RosterRow[]): string;
 /**
  * The exact profile patch block that mounts the roster and the two host
  * services the shipped presets need. `scripts/ensure-profile-rows.sh` carries
  * the same text; a test compares the two so they cannot drift.
  */
-export declare const ROSTER_PATCH_BLOCK = "# dsh-ssh-tui /mode: the agent-preset roster (standard / minimal / PTC /\n# cordis, plus every preset under $DSH_HOME/.agent-presets) and the two host\n# services the shipped presets need. dsh-base composes no roster in a terminal\n# profile, and a third-party bundle patch may not mount an @deepseek-ai row, so\n# the profile's user layer owns them.\n- insert:\n    - id: agent-presets\n      name: '@deepseek-ai/dsh-agent-presets'\n      config:\n        default: standard\n\n    - id: code-runtime\n      name: '@deepseek-ai/dsh-code-runtime-worker-thread'\n\n    - id: subagent-model-selection-settings\n      name: '@deepseek-ai/dsh-tool-subagent/model-selection-settings'\n";
+export declare const ROSTER_PATCH_BLOCK: string;
 /** The profile patch file the roster block belongs in. */
 export declare function rosterPatchPath(home: string, profile: string): string;
+/** One row a patch file declares, with enough position to point at it. */
+export interface PatchRowRef {
+    /** Insert id, or the target of an override/disable entry. */
+    id: string;
+    /** Module name for an insert that mounts one. */
+    name?: string;
+    kind: 'insert' | 'override' | 'disable' | 'other';
+    /** 0-based top-level entry index. */
+    entry: number;
+    /** 0-based index inside the entry's insert list (inserts only). */
+    item?: number;
+    /** 1-based line the id is written on, when the text can be scanned. */
+    line: number;
+}
+export interface PatchAnalysis {
+    /** The YAML parses into a top-level array of patch entries. */
+    parseable: boolean;
+    /** What the loader would reject, when it does not parse. */
+    error?: string;
+    rows: PatchRowRef[];
+}
+/**
+ * Read one patch file into the rows it declares.
+ *
+ * Unparseable YAML is reported instead of thrown: `/doctor` has to *describe*
+ * a broken patch, which is exactly when the loader would refuse to boot.
+ * @param text - the patch file's content.
+ * @returns the rows, and whether the text parsed at all.
+ */
+export declare function analyzePatch(text: string): PatchAnalysis;
+/**
+ * Insert rows that appear more than once, keeping the first occurrence.
+ *
+ * A row is duplicated when an earlier insert declares the same id, or mounts
+ * the same module name — the two ways a second mount reaches the loader and
+ * fails with "service … has been registered". Overrides and disables are never
+ * duplicates of an insert: they target a row instead of mounting it.
+ * @param rows - every row the patch declares.
+ * @returns the later occurrences, in file order.
+ */
+export declare function duplicatePatchRows(rows: readonly PatchRowRef[]): PatchRowRef[];
+/** Whether a patch already declares one roster row, by id or by module name. */
+export declare function patchNamesRow(rows: readonly PatchRowRef[], row: RosterRow): boolean;
+/** The roster rows a patch does not declare yet. */
+export declare function missingRosterRows(rows: readonly PatchRowRef[]): RosterRow[];
+export interface PatchRepair {
+    text: string;
+    /** Roster rows this repair adds, by id. */
+    added: string[];
+    /** Duplicate rows this repair removes, by id, with the line they sat on. */
+    removed: Array<{
+        id: string;
+        line: number;
+    }>;
+}
 /**
- * The patch text with the roster block appended, or `undefined` when the file
- * already names the roster row.
+ * The patch text with the given roster rows mounted, or `undefined` when the
+ * file already declares every one of them.
  *
- * A file that is exactly `[]` (the profile template) is replaced, so the result
- * stays a valid top-level patch list; anything else keeps its content and the
- * block is appended after a blank line.
+ * A row is matched by id or by module name, so a profile that composes the
+ * roster through its own bundle is left alone. A file that is exactly `[]`
+ * (the profile template) is replaced; anything else keeps its content and gains
+ * a new `- insert:` entry after a blank line.
  * @param existing - the patch file's current text.
+ * @param missing - the roster rows to mount; defaults to all of them.
  * @returns the new text, or `undefined` when nothing has to change.
  */
-export declare function rosterPatchText(existing: string): string | undefined;
+export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[]): PatchRepair | undefined;
+/**
+ * The patch text with every repeated insert removed, or `undefined` when the
+ * file has no duplicate.
+ *
+ * Only the later occurrence is cut, and only its own item when the enclosing
+ * `- insert:` entry mounts other rows too. Comments directly above a removed
+ * entry go with it; anything the user wrote around it stays.
+ * @param existing - the patch file's current text.
+ * @returns the new text and what was removed, or `undefined` when nothing is.
+ */
+export declare function planDuplicateRepair(existing: string): PatchRepair | undefined;
 /**
  * Mount the roster in one profile, unless it is already composed.
  *
@@ -42,6 +132,20 @@ export declare function rosterPatchText(existing: string): string | undefined;
  * half-written patch would only be seen by the next launch.
  * @param home - the harness home carrying `profiles/`.
  * @param profile - the profile to patch.
+ * @param missing - the rows to mount; defaults to the whole roster.
  * @returns `present` when the row already exists, else `written`.
  */
-export declare function ensureRosterRows(home: string, profile: string): Promise<'present' | 'written'>;
+export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[]): Promise<'present' | 'written'>;
+/**
+ * Write a repaired patch next to a copy of the previous content.
+ *
+ * `/doctor` changes a file the user owns, so the old text is kept beside it
+ * before anything is replaced. A file that does not exist yet needs no backup.
+ * @param path - the patch file to replace.
+ * @param text - the new content.
+ * @param stamp - filename-safe timestamp for the backup, injectable for tests.
+ * @returns the backup path, or `undefined` when there was nothing to back up.
+ */
+export declare function writePatchWithBackup(path: string, text: string, stamp?: string): Promise<string | undefined>;
+/** The patch text the roster block would produce on its own, for callers that report it. */
+export declare function rosterPatchText(existing: string): string | undefined;