@basou/core 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SimpleGit } from 'simple-git';
 import { ChildProcess } from 'node:child_process';
 
 /**
@@ -50,6 +51,16 @@ declare function summarizeAdapterOutput(_stream: "stdout" | "stderr", _raw: stri
  * capabilities, approval policy, adapter config, and git policy. The
  * `adapters."claude-code"` key uses a hyphen; downstream code accesses it
  * via bracket notation.
+ *
+ * Every object here is `looseObject` (NOT the default strip), so unknown keys
+ * at every level survive parse. The manifest is the declarative source of truth
+ * and is git-tracked and read-modify-written by `basou project` commands; with
+ * the default strip, a field this basou does not recognize — a newer version's
+ * additive field, a future adapter under `adapters`, a hand-added key — would be
+ * silently dropped on the next write. Preserving them keeps basou from destroying
+ * config it does not understand (forward-compatible), while known fields are still
+ * fully type-checked and validated. {@link unknownManifestKeys} surfaces the
+ * unrecognized top-level keys so preservation is not silent.
  */
 declare const ManifestSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"0.1.0">;
@@ -59,15 +70,16 @@ declare const ManifestSchema: z.ZodObject<{
         name: z.ZodString;
         created_at: z.ZodString;
         updated_at: z.ZodString;
-    }, z.core.$strip>;
+        view: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
     project: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         repository_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
     capabilities: z.ZodObject<{
         enabled: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
     approval: z.ZodObject<{
         required_for: z.ZodOptional<z.ZodArray<z.ZodString>>;
         default_risk_level: z.ZodEnum<{
@@ -76,25 +88,63 @@ declare const ManifestSchema: z.ZodObject<{
             high: "high";
             critical: "critical";
         }>;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
     adapters: z.ZodObject<{
         "claude-code": z.ZodObject<{
             enabled: z.ZodBoolean;
             config_path: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
     git: z.ZodObject<{
         events_log: z.ZodDefault<z.ZodEnum<{
             ignore: "ignore";
             commit: "commit";
         }>>;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
     import: z.ZodOptional<z.ZodObject<{
         source_roots: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
+    }, z.core.$loose>>;
+    repos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        visibility: z.ZodOptional<z.ZodEnum<{
+            public: "public";
+            private: "private";
+            "future-public": "future-public";
+        }>>;
+        language: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            ja: "ja";
+            "en+ja": "en+ja";
+        }>>;
+        publishes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                web: "web";
+                npm: "npm";
+            }>;
+            visibility: z.ZodOptional<z.ZodEnum<{
+                public: "public";
+                private: "private";
+                "future-public": "future-public";
+            }>>;
+            language: z.ZodOptional<z.ZodEnum<{
+                en: "en";
+                ja: "ja";
+                "en+ja": "en+ja";
+            }>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
 /** Inferred runtime type for {@link ManifestSchema}. */
 type Manifest = z.infer<typeof ManifestSchema>;
+/**
+ * The unrecognized TOP-LEVEL keys a parsed manifest carries — fields preserved by
+ * the loose schema that this basou does not know. Returned sorted, for surfacing as
+ * an advisory by the read-modify-write commands so preservation is not silent (a
+ * newer version's section, or a hand-added/typo'd key, is flagged rather than
+ * dropped). Nested unknown keys are preserved too but not enumerated here; this is
+ * the high-signal top-level case. Read-only — never mutates.
+ */
+declare function unknownManifestKeys(manifest: Manifest): string[];
 
 declare const SessionInnerImportSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>;
@@ -434,6 +484,10 @@ declare const SessionImportPayloadSchema: z.ZodObject<{
         prev_hash: z.ZodOptional<z.ZodString>;
         type: z.ZodLiteral<"note_added">;
         body: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            note: "note";
+            next_step: "next_step";
+        }>>;
     }, z.core.$strip>, z.ZodObject<{
         schema_version: z.ZodLiteral<"0.1.0">;
         id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
@@ -982,6 +1036,10 @@ declare const NoteAddedEventSchema: z.ZodObject<{
     prev_hash: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"note_added">;
     body: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        note: "note";
+        next_step: "next_step";
+    }>>;
 }, z.core.$strip>;
 declare const AdapterOutputEventSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"0.1.0">;
@@ -1219,6 +1277,10 @@ declare const EventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     prev_hash: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"note_added">;
     body: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        note: "note";
+        next_step: "next_step";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     schema_version: z.ZodLiteral<"0.1.0">;
     id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
@@ -2007,6 +2069,22 @@ type DiffResult = {
  */
 declare function getDiff(repoRoot: string, baseRef: string, headRef: string): Promise<DiffResult>;
 
+/**
+ * Build a {@link SimpleGit} instance bound to `repoRoot`. Production callers
+ * use this single helper so any future tightening (additional safety opts,
+ * environment scrubbing, ...) lands in one place. Test fixtures that need
+ * `unsafe.allowUnsafeConfigPaths` for isolated `GIT_CONFIG_*` paths build
+ * their own SimpleGit locally and intentionally bypass this helper.
+ */
+declare function safeSimpleGit(repoRoot: string): SimpleGit;
+/**
+ * Detect "git executable not found" across error wrappers used by simple-git.
+ * simple-git surfaces spawn errors as `GitError` instances which discard the
+ * original errno `code` property — only the underlying `"spawn git ENOENT"`
+ * text survives in the message string. We therefore check both the errno
+ * `code` (via {@link findErrorCode}) and the message chain.
+ */
+declare function isGitNotFound(error: unknown): boolean;
 /**
  * Payload subset of `git_snapshot` event, mechanically derived from the
  * zod-inferred event type. The wrapping event-shape fields
@@ -3093,6 +3171,11 @@ type DecisionRecord = {
     title: string;
     occurredAt: string;
 };
+type NoteRecord = {
+    body: string;
+    sessionId: string;
+    occurredAt: string;
+};
 type PendingApproval = {
     id: string;
     risk: string;
@@ -3149,6 +3232,11 @@ type OrientationSummary = {
     /** Most recent `decision_recorded` across all sessions; null when none. */
     latestDecision: DecisionRecord | null;
     decisionCount: number;
+    /**
+     * Most recent `note_added` over non-archived sessions — the recorded next
+     * step / handoff ("次の起点") surfaced in the forward section; null when none.
+     */
+    latestNote: NoteRecord | null;
     /** related_files of the latest session, deduped + sorted + capped at the display limit. */
     relatedFiles: {
         displayed: string[];
@@ -3165,6 +3253,14 @@ type OrientationSummary = {
         newestStartedAt: string | null;
         /** source.kind of the newest non-archived session, or null when none captured. */
         newestSource: string | null;
+        /**
+         * Tail of captured activity over non-archived sessions = max of each
+         * session's boundary (`ended_at` ?? `started_at`) and every captured event's
+         * `occurred_at`. Folding event times covers a live session whose `ended_at`
+         * is not yet written. Used to flag a latest-recorded decision that trails
+         * real activity; null when no non-archived sessions exist.
+         */
+        latestActivityAt: string | null;
         /** Session counts per source kind, sorted by kind. Counts only — never volume/time. */
         bySource: SourceCount[];
         /** manifest `import.source_roots`, or null when single-root / unreadable. */
@@ -3200,6 +3296,884 @@ declare function summarizeOrientation(input: OrientationRendererInput): Promise<
  */
 declare function renderOrientation(input: OrientationRendererInput): Promise<OrientationRendererResult>;
 
+/**
+ * Project roster drift (the "saddle" model). A project's repos are DECLARED
+ * once in the manifest's `repos` list; the capture config (`source_roots`) must
+ * cover every declared repo. This computes the drift between the two so
+ * `basou project check` can surface a declared repo that is NOT being captured
+ * — the class of bug where a companion repo was wired into the workspace but
+ * never added to `source_roots`, so its work silently fell out of capture.
+ *
+ * Pure: it compares declared relative paths against captured relative paths and
+ * performs no filesystem or git I/O. Paths are compared as declared (both lists
+ * use the same machine-portable relative-path form), not resolved on disk.
+ */
+type RepoVisibility = "public" | "private" | "future-public";
+/**
+ * The audience-driven language axis. Independent of visibility: a private repo
+ * can publish English content, a public repo can carry bilingual docs. `en` /
+ * `ja` for a single audience, `en+ja` when both are served.
+ */
+type RepoLanguage = "en" | "ja" | "en+ja";
+/** A published surface a repo emits: a deployed website or a package registry. */
+type PublishKind = "web" | "npm";
+/**
+ * One published surface. Its visibility and language are INDEPENDENT of the
+ * source repo's: a private repo commonly publishes a public website. Both are
+ * optional so a surface can be declared
+ * before those facts are pinned down (mirroring how `adopt` leaves repo
+ * visibility unset for the operator to fill in).
+ */
+type PublishTarget = {
+    kind: PublishKind;
+    visibility?: RepoVisibility | undefined;
+    language?: RepoLanguage | undefined;
+};
+type RepoEntry = {
+    /** Path relative to the manifest repo root (e.g. ".", "../takuhon"). */
+    path: string;
+    visibility?: RepoVisibility | undefined;
+    /** Source language (commits/comments/code, read by contributors). Independent of visibility. */
+    language?: RepoLanguage | undefined;
+    /** Published surfaces this repo emits (opt-in; absent for a repo that publishes nothing). */
+    publishes?: PublishTarget[] | undefined;
+};
+type RosterDriftSummary = {
+    declaredCount: number;
+    capturedCount: number;
+    /** Declared in `repos` but absent from `source_roots`: a capture gap. */
+    gaps: RepoEntry[];
+    /** In `source_roots` but not declared in `repos` (e.g. a workspace view, or a stray). */
+    extra: string[];
+    /** Declared paths that are also captured. */
+    matched: string[];
+    /** True when there is no capture gap (every declared repo is covered). */
+    ok: boolean;
+};
+/**
+ * Compute the {@link RosterDriftSummary} for a project. A declared repo missing
+ * from the captured set is a `gap` (the surfaced suspicion); a captured path not
+ * in the declared set is `extra` (commonly the workspace view, which is a
+ * capture source but not itself a project repo). With no declared roster, there
+ * are no gaps (nothing to check against) and every captured path is `extra`.
+ */
+declare function summarizeRosterDrift(input: {
+    repos?: RepoEntry[];
+    sourceRoots?: string[];
+}): RosterDriftSummary;
+type SourceRootsReconcile = {
+    /**
+     * The reconciled `source_roots`: the existing entries verbatim, then every
+     * declared repo path that was missing (normalized, in roster order). Existing
+     * order and form are preserved so the manifest diff is minimal and reversible.
+     */
+    next: string[];
+    /** Declared repo paths (normalized) that were appended because `source_roots` did not cover them. */
+    added: string[];
+    /** True when `source_roots` already covers every declared repo (`next` equals the current list). */
+    unchanged: boolean;
+};
+/**
+ * Derive the `source_roots` a project's declared repo roster requires. The
+ * roster (`repos`) is the single source of truth for which repos belong to the
+ * project; this is the actuator behind `basou project sync`, computing the
+ * additive reconciliation so every declared repo is captured.
+ *
+ * ADDITIVE ONLY: it appends declared paths that are missing and never removes
+ * an existing entry. A captured-but-undeclared path (commonly the generated
+ * workspace view — a legitimate capture source that is not itself a project
+ * repo) is preserved; pruning strays is deferred to the slice that generates
+ * the view (so basou knows which extras it owns). Existing entries are kept
+ * byte-identical; only appended paths are normalized.
+ *
+ * Pure: no filesystem or git I/O. Paths are compared in the same normalized
+ * form as {@link summarizeRosterDrift}, so a trailing-slash variant of an
+ * already-captured repo is not re-appended.
+ */
+declare function reconcileSourceRoots(input: {
+    repos?: RepoEntry[];
+    sourceRoots?: string[];
+}): SourceRootsReconcile;
+/**
+ * On-disk classification of a source-root candidate during adoption: a git repo
+ * root (→ becomes a roster entry), a resolved-but-non-repo directory (the
+ * generated workspace view, `/tmp`, a scratch dir → excluded), or a path that
+ * could not be resolved on disk (→ excluded).
+ */
+type AdoptCandidateKind = "repo" | "non-repo" | "unresolved";
+type AdoptCandidate = {
+    /** Source-root path as declared (relative to the manifest root). */
+    path: string;
+    /** On-disk classification; the filesystem probing that produces it is the caller's job. */
+    kind: AdoptCandidateKind;
+};
+type RosterAdoptionPlan = {
+    /** Proposed `repos` entries: the candidates that are git repos (visibility left unset for the operator). */
+    repos: RepoEntry[];
+    /** Candidates excluded from the roster, with why (a non-repo directory, or an unresolvable path). */
+    excluded: {
+        path: string;
+        kind: Exclude<AdoptCandidateKind, "repo">;
+    }[];
+};
+/**
+ * Plan a `repos` roster from classified source-root candidates (the actuator
+ * behind `basou project adopt`). Pure: it partitions already-classified
+ * candidates — the realpath / `.git` filesystem probing that produces each
+ * `kind` is the caller's job, so this stays testable without disk I/O.
+ *
+ * A git repo becomes a roster entry (path only; visibility is left unset because
+ * it is a human judgment, kept independent of the other axes). A non-repo
+ * (commonly the generated workspace view) or an unresolvable path is excluded and
+ * reported, so the operator sees what was dropped and why before editing. Repo
+ * paths are deduped by normalized form, preserving the first declared form and
+ * order.
+ */
+declare function planRosterAdoption(candidates: AdoptCandidate[]): RosterAdoptionPlan;
+
+/**
+ * Archive (fold) a repo out of a project's declared roster — the inverse of
+ * `adopt` + `sync`, and the first PRUNING step in the saddle model (every prior
+ * slice was additive and deliberately deferred removal). When a repo has served
+ * its purpose, archiving removes it from the declared `repos` roster and prunes
+ * its capture entry from `source_roots`, so it is no longer part of the project
+ * or scanned by `refresh`.
+ *
+ * Pure: it computes the manifest mutation from the DECLARED lists alone — no
+ * filesystem or git I/O — so it works even when the repo is already gone from
+ * disk (the common "I deleted the repo, now clean basou" case). Historical
+ * captured data in the anchor is NOT touched (archiving stops future capture,
+ * it does not erase the past). The repo-side wiring teardown (view symlink,
+ * instruction symlinks, .gitignore, canonical) is the caller's separate,
+ * higher-blast-radius concern; this only mutates the manifest's declaration.
+ */
+
+type ArchivePlan = {
+    /** The normalized target path being archived. */
+    target: string;
+    /** True when the target is declared in the roster. */
+    found: boolean;
+    /**
+     * True when the target resolves to the anchor/host (`.`). Archiving the
+     * project's own root is refused: it is the home of the manifest, not a member
+     * repo to fold. The caller writes nothing in this case.
+     */
+    isAnchor: boolean;
+    /** The roster entry that would be removed (echoed for the report); set only when found & not anchor. */
+    rosterEntry?: RepoEntry | undefined;
+    /** The roster after removal. An empty array means the project closes (the `repos` key is dropped). */
+    nextRepos: RepoEntry[];
+    /** True when removal leaves the roster empty (the unified-instruction project is fully closed). */
+    reposEmptied: boolean;
+    /** The `source_roots` entry (normalized) that would be pruned; set only when the target was captured. */
+    sourceRootRemoval?: string | undefined;
+    /** The `source_roots` after pruning; set only when a prune actually happens. */
+    nextSourceRoots?: string[] | undefined;
+    /** Declared repos remaining after removal. */
+    remainingCount: number;
+    /** True when exactly one repo remains: the project becomes solo and the workspace view is no longer needed. */
+    becomesSolo: boolean;
+};
+/**
+ * Compute the {@link ArchivePlan} for folding `target` out of the project. Pure:
+ * it partitions the declared `repos` and `source_roots` by normalized path.
+ *
+ * - Archiving the anchor (`.`, or a path the caller resolved to the manifest
+ *   root) is refused — the plan reports `isAnchor` and removes nothing.
+ * - A target not in the roster yields `found: false` and no change (the caller
+ *   reports the declared paths so the operator sees what to type).
+ * - Otherwise EVERY roster entry matching the normalized target is removed (so a
+ *   path declared twice does not survive), and the matching `source_roots` entry
+ *   (commonly the same path) is pruned. Only the EXACT normalized target is
+ *   pruned from `source_roots`; entries for every other path — the host `.`, a
+ *   generated workspace-view source root — survive.
+ * - When removal empties the roster, `nextRepos` is `[]` and `reposEmptied` is
+ *   true (the caller drops the `repos` key — `repos: []` is not a valid roster).
+ */
+declare function planArchive(input: {
+    repos?: RepoEntry[];
+    sourceRoots?: string[];
+    target: string;
+    targetIsAnchor?: boolean;
+}): ArchivePlan;
+
+/**
+ * Plan the agent instruction-file `.gitignore` entries a declared repo needs
+ * (the first generation step of the "saddle" model). For a public-facing repo,
+ * the agent instruction files (AGENTS.md, CLAUDE.md, …) must be GITIGNORED so the
+ * gitignored symlinks to the private canonical never enter public git history.
+ * `basou project gitignore` reconciles each repo's `.gitignore` to that; this is
+ * the pure planner behind it.
+ *
+ * Pure: it diffs the REQUIRED patterns against the repo's CURRENT `.gitignore`
+ * lines (both gathered by the caller) and reports only what is MISSING — it never
+ * proposes removing a line. The realpath / file reading / writing is the caller's
+ * job. The privacy decision is visibility-aware: only public / future-public
+ * repos require the patterns (a private anchor may legitimately track its
+ * canonical), and a repo with unset visibility is skipped (reported), never
+ * acted on by guesswork.
+ */
+
+/** A declared repo's current `.gitignore` state, gathered by the caller. */
+type RepoGitignoreFacts = {
+    /** Roster repo path (relative to the manifest root). */
+    path: string;
+    /** Declared visibility; undefined when the operator has not set it yet. */
+    visibility?: RepoVisibility | undefined;
+    /** False when the repo path could not be resolved / is not a usable git repo. */
+    reachable: boolean;
+    /** Existing `.gitignore` lines, trimmed; an empty array when there is no `.gitignore`. */
+    currentLines: string[];
+};
+/** The patterns to ADD to one repo's `.gitignore` (never any to remove). */
+type RepoGitignorePlan = {
+    path: string;
+    toAdd: string[];
+};
+type GitignorePlanSummary = {
+    /** Repos that need patterns added (those with an empty `toAdd` are omitted). */
+    plans: RepoGitignorePlan[];
+    /** Repo paths skipped because visibility is unset (cannot decide safely). */
+    unknown: string[];
+    /** Repo paths that could not be resolved / are not usable git repos. */
+    unreachable: string[];
+    /**
+     * True only when nothing needs adding AND every repo was judgeable and
+     * reachable — so a clean verdict is never claimed while some repos were
+     * skipped (unset visibility) or could not be inspected (unreachable).
+     */
+    ok: boolean;
+};
+/**
+ * Compute the {@link GitignorePlanSummary}: for each public-facing, reachable
+ * repo, the `required` patterns that are not already present in its `.gitignore`
+ * (compared by trimmed exact line). Private repos require nothing; unset
+ * visibility is reported as `unknown` and unreachable repos as `unreachable`.
+ * `ok` is true when no repo needs any addition.
+ */
+declare function planGitignore(input: {
+    repos: RepoGitignoreFacts[];
+    required: string[];
+}): GitignorePlanSummary;
+
+/**
+ * Agent instruction-file "A preset" generation. A repo's
+ * canonical instruction file splits into a STABLE PRESET (its source
+ * visibility, source language, and published surfaces — facts derived from the
+ * manifest) and a HAND-AUTHORED POLICY (tech choices, coding rules). This
+ * renders the stable preset from the declaration so the operator stops
+ * hand-typing it into every prompt, and plans how that generated region
+ * reconciles against each repo's canonical — so `basou project preset` keeps it
+ * in sync without ever touching the hand-authored content around it.
+ *
+ * Pure: it renders deterministic markdown from declared fields and judges
+ * already-gathered facts (does the canonical exist? what does its generated
+ * region currently hold?). The filesystem / marker reading / writing is the
+ * caller's job.
+ */
+
+/** The declared fields the preset block is rendered from. */
+type PresetRepo = {
+    visibility?: RepoVisibility | undefined;
+    language?: RepoLanguage | undefined;
+    publishes?: PublishTarget[] | undefined;
+};
+/**
+ * Whether a repo has anything to render. A repo with no visibility, no language,
+ * and no published surface yields an all-"未設定" block that helps no one, so it
+ * is reported as `undeclared` rather than generated.
+ */
+declare function isRenderable(repo: PresetRepo): boolean;
+/**
+ * Render the stable-preset markdown block (the content that lives BETWEEN the
+ * BASOU:GENERATED markers in a canonical). Deterministic and OSS-generic: it
+ * derives entirely from the declared fields, embedding no operator-specific
+ * names, so re-running on an unchanged manifest produces byte-identical output
+ * (the basis for drift detection). The published surfaces are listed in their
+ * declared order. Returns the block WITHOUT a trailing newline; the marker
+ * writer adds the surrounding structure.
+ */
+declare function renderPresetBlock(repo: PresetRepo): string;
+/**
+ * The canonical's marker state as parsed by the caller (mirrors
+ * `markdown-store`'s `MarkerSection.kind`). `ok` means exactly one well-ordered
+ * marker pair; any other value means the generated region cannot be located
+ * safely, so the preset is NOT injected (we never clobber a hand-authored file).
+ */
+type PresetMarkerKind = "ok" | "no_markers" | "missing_start" | "missing_end" | "multiple_pairs" | "wrong_order";
+/** The gathered facts for one declared repo. */
+type RepoPresetFacts = {
+    /** Roster repo path (relative to the manifest root). */
+    path: string;
+    /** True when this repo IS the project anchor (its own AGENTS.md is hand-maintained; skipped). */
+    isAnchor: boolean;
+    /** False when the repo path could not be resolved / is not a usable git repo. */
+    reachable: boolean;
+    /** Declared fields (the render input). */
+    visibility?: RepoVisibility | undefined;
+    language?: RepoLanguage | undefined;
+    publishes?: PublishTarget[] | undefined;
+    /**
+     * The canonical's repo name (`<name>` in `agents/<name>/AGENTS.md`). Two
+     * DISTINCT repos sharing it would write to one canonical, so it is used to
+     * detect that. Set by the caller for reachable, non-anchor repos.
+     */
+    canonicalName?: string | undefined;
+    /** Whether the canonical file exists on disk. */
+    canonicalPresent: boolean;
+    /**
+     * Whether the present canonical could be read. Defaults to readable; the
+     * caller sets it `false` when the file exists but a non-ENOENT read failed
+     * (e.g. it is a directory, or permission denied), so one bad canonical
+     * degrades only that repo instead of crashing the whole report.
+     */
+    canonicalReadable?: boolean | undefined;
+    /** Marker parse result of the canonical (only meaningful when present and readable). */
+    markerKind?: PresetMarkerKind | undefined;
+    /** Current generated-region content (only when `markerKind === "ok"`). */
+    currentBlock?: string | undefined;
+};
+/** `create` seeds an absent canonical; `update` replaces the region of an existing one. */
+type PresetAction = "create" | "update";
+/** A repo whose canonical's generated region will be created or updated. */
+type RepoPresetPlan = {
+    path: string;
+    canonicalName: string;
+    action: PresetAction;
+    /** The block that will be written (the marker-delimited content). */
+    desiredBlock: string;
+};
+/**
+ * A canonical that exists but whose markers cannot be located safely (absent or
+ * malformed). The region is NOT injected — surfaced so the operator can add the
+ * markers (or remove the malformed ones) by hand.
+ */
+type PresetMarkerConflict = {
+    repo: string;
+    reason: Exclude<PresetMarkerKind, "ok">;
+};
+/**
+ * Two or more DISTINCT declared repos whose canonical resolves to the same
+ * `agents/<canonicalName>/AGENTS.md`. They would write over one canonical, so
+ * neither is generated; the operator must disambiguate.
+ */
+type PresetCollision = {
+    canonicalName: string;
+    repos: string[];
+};
+type PresetPlanSummary = {
+    /** Repos whose canonical's generated region will be created/updated (only those with work). */
+    plans: RepoPresetPlan[];
+    /** Repos already in sync (canonical present, ok markers, block matches). */
+    inSync: string[];
+    /** Repos with nothing declared to render (no visibility, language, or published surface). */
+    undeclared: string[];
+    /** Canonicals that exist but whose markers are absent/malformed — not overwritten. */
+    markerConflicts: PresetMarkerConflict[];
+    /** Repos whose canonical exists but could not be read (degraded, not generated). */
+    unreadable: string[];
+    /** Groups of distinct repos that resolve to the same canonical (ambiguous; not generated). */
+    collisions: PresetCollision[];
+    /** Repos that resolve to the anchor (their own AGENTS.md is hand-maintained; skipped). */
+    anchors: string[];
+    /** Repo paths that could not be resolved / are not usable git repos. */
+    unreachable: string[];
+    /**
+     * True only when nothing needs writing AND there are no marker conflicts, no
+     * unreadable canonicals, no collisions, no unreachable repos, and no
+     * undeclared repos — so a clean "all in sync" verdict is never claimed while
+     * some repo was skipped or unjudgeable. Anchors do not block it (they are
+     * intentionally not generated).
+     */
+    ok: boolean;
+};
+/**
+ * Compute the {@link PresetPlanSummary} from per-repo facts. For each declared,
+ * non-anchor, reachable, renderable repo: an absent canonical is a `create`, an
+ * existing canonical with an `ok` marker region is an `update` (or `inSync` when
+ * the region already matches), and a canonical with absent/malformed markers is
+ * a {@link PresetMarkerConflict} (never overwritten). The anchor is skipped
+ * (`anchors`), an unrenderable repo is `undeclared`, and an unresolvable repo is
+ * `unreachable`.
+ *
+ * Robustness:
+ * - Facts are deduped by normalized path (first wins), so a repo listed twice
+ *   never yields duplicate plans / report entries.
+ * - Two DISTINCT repos resolving to the same canonical name are a
+ *   {@link PresetCollision} and neither is generated (silent clobbering of one
+ *   canonical is surfaced, not actioned).
+ */
+declare function summarizePresetPlan(facts: RepoPresetFacts[]): PresetPlanSummary;
+
+/**
+ * Rename (re-path) a repo in a project's declared roster. When a repo's
+ * directory is moved or renamed on disk, its declared `path` (and the matching
+ * `source_roots` capture entry) must follow, or the roster drifts from reality.
+ * This is the saddle model's maintenance counterpart to `archive` — it mutates
+ * the manifest's path references rather than removing them.
+ *
+ * Pure: it computes the mutation from the DECLARED lists alone — no filesystem
+ * or git I/O — so it works regardless of whether the move has happened on disk
+ * yet. The repo-side wiring that embeds the old basename (the anchor canonical
+ * `agents/<basename>/AGENTS.md`, the workspace-view symlink, the relative
+ * targets of the repo's own instruction symlinks) is the caller's separate
+ * concern; this only re-paths the declaration.
+ */
+
+type RenamePlan = {
+    /** The normalized source path being renamed. */
+    oldTarget: string;
+    /** The normalized destination path. */
+    newTarget: string;
+    /** True when old and new normalize to the same path (nothing to do). */
+    noop: boolean;
+    /**
+     * True when the source resolves to the anchor/host (`.`). Renaming the
+     * project's own root is refused; the caller writes nothing.
+     */
+    isAnchor: boolean;
+    /** True when the source path is declared in the roster. */
+    found: boolean;
+    /** True when the destination path is ALREADY declared (a distinct entry) — refused to avoid a duplicate. */
+    collision: boolean;
+    /** The roster entry being renamed (echoed for the report); set only in the actionable case. */
+    rosterEntry?: RepoEntry | undefined;
+    /** The roster after re-pathing the entry (other fields preserved). */
+    nextRepos: RepoEntry[];
+    /** True when the roster changed. */
+    reposChanged: boolean;
+    /** The old normalized path that was re-pathed in `source_roots`; set only when it was captured. */
+    sourceRootRenamed?: string | undefined;
+    /** The `source_roots` after re-pathing; set only when a rename happened. */
+    nextSourceRoots?: string[] | undefined;
+    /** True when the basename changes (old/new last segment differ) — the repo-side canonical/view names need renaming too. */
+    basenameChanged: boolean;
+};
+/** The last path segment of a normalized relative path (e.g. "../a/x" => "x", "." => "."). */
+declare function pathBasename(p: string): string;
+/**
+ * Compute the {@link RenamePlan} for re-pathing `oldPath` to `newPath`. Pure: it
+ * re-maps the declared `repos` and `source_roots` by normalized path.
+ *
+ * - A no-op (old === new), renaming the anchor, a source not in the roster, or a
+ *   destination that already exists as a distinct entry (collision) all change
+ *   nothing — the caller writes nothing and the report explains.
+ * - Otherwise EVERY roster entry matching the old path is re-pathed to the new
+ *   path (preserving its visibility/language/publishes), and the result is
+ *   deduped (so an old path declared twice collapses to one new entry). The
+ *   matching `source_roots` entry (commonly the same path) is re-pathed and
+ *   deduped likewise; all other entries (the host `.`, a view source root) keep
+ *   their position and form.
+ */
+declare function planRename(input: {
+    repos?: RepoEntry[];
+    sourceRoots?: string[];
+    oldPath: string;
+    newPath: string;
+    oldIsAnchor?: boolean;
+}): RenamePlan;
+
+/**
+ * Plan the agent instruction-file symlinks a declared repo needs (the
+ * generation step that follows `basou project gitignore` in the "saddle"
+ * model). Each repo's agent instruction files are GITIGNORED symlinks that
+ * resolve to a single canonical source kept in the project's private anchor —
+ * so the canonical (which may carry private planning content) is edited once
+ * and every CLI reads it through a symlink, never committed to a public repo's
+ * history.
+ *
+ * The on-disk topology (verified against the operator's live environment) is a
+ * hub-and-spoke:
+ *
+ *   <repo>/AGENTS.md                       -> <anchor>/agents/<repo>/AGENTS.md   (the hub → canonical)
+ *   <repo>/CLAUDE.md                       -> AGENTS.md                          (a spoke → the hub)
+ *   <repo>/.github/copilot-instructions.md -> ../AGENTS.md                       (a spoke → the hub)
+ *
+ * Only AGENTS.md points at the anchor's canonical; CLAUDE.md and Copilot point
+ * back at the repo's own AGENTS.md, so there is exactly one link per repo that
+ * depends on the anchor path. GEMINI.md is intentionally not generated (the
+ * Gemini CLI was discontinued for personal use).
+ *
+ * Pure: it judges already-gathered, per-file facts (does the link exist? does
+ * it point where it should?) and reports only what is MISSING. It never
+ * proposes overwriting an existing file or repointing a link that points
+ * elsewhere — those surface as conflicts for the operator to resolve by hand
+ * (non-destructive, like the additive `.gitignore` planner). The realpath /
+ * symlink reading / writing is the caller's job.
+ */
+/**
+ * The on-disk state of one instruction file relative to the symlink it should
+ * be. `correct` = the expected link already exists (idempotent skip); `missing`
+ * = nothing there (ENOENT), so it can be created; `mismatch` = a symlink
+ * pointing somewhere else; `occupied` = a real file or directory; `blocked` =
+ * the path could not be inspected (e.g. a parent component is a file → ENOTDIR,
+ * or permission denied). Only `missing` is actionable; the rest are left
+ * untouched. `blocked` is distinct from `missing` so a non-ENOENT lstat error
+ * is never mistaken for a creatable gap (which would crash `--apply`).
+ */
+type InstructionSymlinkState = "correct" | "missing" | "mismatch" | "occupied" | "blocked";
+/** The gathered facts for one instruction file in one declared repo. */
+type InstructionSymlinkFact = {
+    /** Repo-relative file name, e.g. "AGENTS.md", ".github/copilot-instructions.md". */
+    name: string;
+    /** The relative symlink target this file should have (computed by the caller). */
+    expectedTarget: string;
+    /** On-disk state of the path. */
+    state: InstructionSymlinkState;
+    /** The link's current target, present only when `state` is `mismatch`. */
+    actualTarget?: string;
+};
+/** The gathered symlink facts for one declared repo. */
+type RepoSymlinkFacts = {
+    /** Roster repo path (relative to the manifest root). */
+    path: string;
+    /**
+     * True when this repo IS the project anchor (it owns the canonical sources, so
+     * it never links to itself). An anchor entry is skipped entirely.
+     */
+    isAnchor: boolean;
+    /** False when the repo path could not be resolved / is not a usable git repo. */
+    reachable: boolean;
+    /**
+     * Whether the anchor's canonical source for this repo
+     * (`<anchor>/agents/<repo>/AGENTS.md`) exists. Without it the hub link would
+     * dangle, so no links are planned (reported as a missing canonical instead).
+     */
+    canonicalPresent: boolean;
+    /**
+     * The canonical's repo name (the `<repo>` in `agents/<repo>/AGENTS.md`) this
+     * repo wires to. Two DISTINCT repos sharing one canonical name would silently
+     * collide on a single canonical, so it is used to detect that. Set by the
+     * caller for reachable, canonical-present repos; undefined otherwise.
+     */
+    canonicalName?: string;
+    /** Per instruction-file facts (empty when anchor / unreachable / canonical absent). */
+    files: InstructionSymlinkFact[];
+};
+/** The instruction-file symlinks to CREATE in one repo (only the `missing` ones). */
+type RepoSymlinkPlan = {
+    path: string;
+    toCreate: {
+        name: string;
+        target: string;
+    }[];
+};
+/**
+ * A symlink that already exists but is not what we would generate: a symlink
+ * pointing elsewhere (`mismatch`), a real file/directory (`occupied`), or a path
+ * that could not be inspected (`blocked`, e.g. a parent is a file). Surfaced,
+ * never overwritten.
+ */
+type SymlinkConflict = {
+    repo: string;
+    file: string;
+    reason: "mismatch" | "occupied" | "blocked";
+    /** The conflicting link's current target, present only when `reason` is `mismatch`. */
+    actualTarget?: string;
+};
+/**
+ * Two or more DISTINCT declared repos whose canonical resolves to the same
+ * `agents/<canonicalName>/AGENTS.md`. They would silently share one canonical,
+ * so neither is auto-wired; the operator must disambiguate.
+ */
+type SymlinkCollision = {
+    canonicalName: string;
+    repos: string[];
+};
+type SymlinkPlanSummary = {
+    /** Repos with at least one link to create (those with nothing to create are omitted). */
+    plans: RepoSymlinkPlan[];
+    /** Existing files/links that block generation and are left untouched for the operator. */
+    conflicts: SymlinkConflict[];
+    /** Repo paths whose anchor canonical (`agents/<repo>/AGENTS.md`) is absent, so nothing can be wired. */
+    missingCanonical: string[];
+    /** Repo paths that could not be resolved / are not usable git repos. */
+    unreachable: string[];
+    /** Groups of distinct repos that resolve to the same canonical (ambiguous; not auto-wired). */
+    collisions: SymlinkCollision[];
+    /**
+     * True only when nothing needs creating AND there are no conflicts, no missing
+     * canonicals, no unreachable repos, and no collisions — so a clean "all wired"
+     * verdict is never claimed while some repo was blocked, ambiguous, or could not
+     * be inspected.
+     */
+    ok: boolean;
+};
+/**
+ * Compute the {@link SymlinkPlanSummary} from per-repo facts. For each declared,
+ * non-anchor, reachable repo whose canonical exists: a `missing` link becomes a
+ * create, a `mismatch`/`occupied`/`blocked` link becomes a {@link SymlinkConflict}
+ * (never a create — we do not overwrite), and a `correct` link is a no-op. The
+ * anchor is skipped (it owns the canonical), an absent canonical is reported as
+ * `missingCanonical` (no links planned, since the hub would dangle), and an
+ * unresolvable repo as `unreachable`.
+ *
+ * Robustness:
+ * - Facts are deduped by normalized path (first wins), so a repo listed twice in
+ *   the manifest never yields duplicate plans (which would make `--apply` create
+ *   the same link twice → EEXIST) or duplicate report entries.
+ * - Two DISTINCT repos resolving to the same canonical name are reported as a
+ *   {@link SymlinkCollision} and neither is auto-wired (silent sharing of one
+ *   canonical is surfaced, not actioned).
+ *
+ * `ok` is true only when there is genuinely nothing to do and every repo was
+ * judgeable, reachable, and unambiguous.
+ */
+declare function summarizeSymlinkPlan(facts: RepoSymlinkFacts[]): SymlinkPlanSummary;
+
+/**
+ * Agent instruction-file wiring (the read-only first step of the "saddle"
+ * model's view/instruction/gitignore generation). For each declared repo, the
+ * agent instruction files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md)
+ * should be present as GITIGNORED symlinks to a canonical source, never tracked
+ * in a public repo's git history (where they would expose the private canonical
+ * content they point at). This summarizes the on-disk + git facts the CLI
+ * gathers and surfaces the privacy-relevant drift; it generates nothing.
+ *
+ * Pure: it judges already-gathered facts (presence + git-tracked status). The
+ * filesystem / git probing that produces those facts is the caller's job.
+ */
+
+/** On-disk + git state of one instruction file in one repo. */
+type InstructionFileFact = {
+    /** Repo-relative file name, e.g. "AGENTS.md", ".github/copilot-instructions.md". */
+    name: string;
+    /** Exists on disk (a regular file or a symlink, including a broken one). */
+    present: boolean;
+    /** Tracked by the repo's git (committed / staged). */
+    tracked: boolean;
+};
+/** The gathered wiring facts for one declared repo. */
+type RepoWiringFacts = {
+    /** Roster repo path (relative to the manifest root). */
+    path: string;
+    /** Declared visibility; undefined when the operator has not set it yet. */
+    visibility?: RepoVisibility | undefined;
+    /** False when the repo path could not be resolved / is not a usable git repo. */
+    reachable: boolean;
+    /** Per instruction-file facts (omitted/empty when unreachable). */
+    instructionFiles: InstructionFileFact[];
+};
+/**
+ * A privacy risk: a public-facing repo tracks an instruction file in git, which
+ * can expose the private canonical content the file points at.
+ */
+type WiringRisk = {
+    repo: string;
+    visibility: Extract<RepoVisibility, "public" | "future-public">;
+    file: string;
+};
+type WiringSummary = {
+    /** Echo of the per-repo facts (for `--json` and the detailed view). */
+    repos: RepoWiringFacts[];
+    /** Public / future-public repos with a tracked instruction file. */
+    risks: WiringRisk[];
+    /** Repo paths whose visibility is unset, so the privacy verdict cannot be judged. */
+    unknown: string[];
+    /** Repos missing one or more instruction files (a wiring gap a later generate slice fills). */
+    incomplete: {
+        repo: string;
+        missing: string[];
+    }[];
+    /** Repo paths that could not be resolved / are not usable git repos. */
+    unreachable: string[];
+    /** True when there are no risks, no unknown visibility, and no unreachable repos. */
+    ok: boolean;
+};
+/**
+ * Summarize {@link RepoWiringFacts} into the privacy-relevant verdict. A
+ * public-facing repo that TRACKS an instruction file is a {@link WiringRisk}
+ * (its git history can expose the private canonical it points at); a repo with
+ * unset visibility cannot be judged (`unknown`); a repo missing instruction
+ * files is `incomplete` (a wiring gap, not a privacy problem). `ok` is true only
+ * when nothing is at risk, every repo is judgeable, and every repo is reachable.
+ */
+declare function summarizeWiring(facts: RepoWiringFacts[]): WiringSummary;
+
+/**
+ * Plan the symlinks a project's throwaway "view" needs (the generation step
+ * after the instruction-file symlinks in the "saddle" model). When a project
+ * has 2+ repos, basou generates a view directory that aggregates every roster
+ * repo via one symlink each, named by the repo's basename and pointing at the
+ * repo (relative to the view):
+ *
+ *   <view>/app     -> ../app
+ *   <view>/anchor  -> ../anchor   (the anchor's "." entry is aggregated here too,
+ *   <view>/app-site -> ../app-site   unlike the instruction symlinks)
+ *
+ * The view is git-unmanaged and regenerable; its location is declared once
+ * (`workspace.view` in the manifest) and its contents are derived from the
+ * roster. This is the pure planner: it judges already-gathered, per-repo facts
+ * (does the view link exist? does it point at the repo?) and reports only what
+ * is MISSING. It never overwrites an existing file or repoints a link that
+ * points elsewhere — those surface as conflicts for the operator to resolve by
+ * hand (non-destructive). The realpath / readlink / symlink I/O is the caller's
+ * job.
+ *
+ * Pruning stray entries already in the view IS now in scope (see `toPrune` /
+ * `strayUnknown` and {@link ExistingViewLink}): the ownership model that tells an
+ * orphaned repo link from the view's own instruction files / local state lives
+ * here. Still NOT in scope: generating the view's own instruction files.
+ */
+/**
+ * The on-disk state of one repo's view symlink. `correct` = the expected link
+ * exists (idempotent skip); `missing` = nothing there (ENOENT) so it can be
+ * created; `mismatch` = a symlink pointing elsewhere; `occupied` = a real file
+ * or directory; `blocked` = the path could not be inspected (a non-ENOENT lstat
+ * error, e.g. a parent component is a file). Only `missing` is actionable.
+ */
+type ViewLinkState = "correct" | "missing" | "mismatch" | "occupied" | "blocked";
+/** The gathered facts for one roster repo's place in the view. */
+type ViewRepoFact = {
+    /** Roster repo path (relative to the manifest root), e.g. ".", "../basou". */
+    path: string;
+    /**
+     * False when the repo cannot be aggregated into the view: its path did not
+     * resolve on disk, or it resolves to the view directory itself (a self-link).
+     */
+    reachable: boolean;
+    /** The view symlink name (the repo's basename), e.g. "basou". Set when reachable. */
+    linkName?: string;
+    /** The relative target the view link should have, e.g. "../basou". Set when reachable. */
+    expectedTarget?: string;
+    /** On-disk state of `<view>/<linkName>`. Set when reachable. */
+    state?: ViewLinkState;
+    /** The link's current target, present only when `state` is `mismatch`. */
+    actualTarget?: string;
+};
+/**
+ * An existing view entry that is not what we would generate: a symlink pointing
+ * elsewhere (`mismatch`), a real file/directory (`occupied`), or an
+ * uninspectable path (`blocked`). Surfaced, never overwritten.
+ */
+type ViewConflict = {
+    name: string;
+    reason: "mismatch" | "occupied" | "blocked";
+    /** The conflicting link's current target, present only when `reason` is `mismatch`. */
+    actualTarget?: string;
+};
+/**
+ * Two or more DISTINCT roster repos whose basename is the same, so they would
+ * collide on a single `<view>/<basename>` link. Neither is auto-wired; the
+ * operator must disambiguate.
+ */
+type ViewCollision = {
+    linkName: string;
+    repos: string[];
+};
+/**
+ * An entry actually present in the view directory, pre-classified by the caller's
+ * filesystem probe, for stray detection (the inverse of generation). Only
+ * symlinks are candidates — a real file or directory is never the caller's to
+ * remove and is not gathered here. `kind` tells the planner whether a symlink not
+ * tied to any roster repo is a basou-generated repo link safe to prune:
+ *
+ * - `repo`: a relative target that follows to an existing git repository — a
+ *   directory containing a `.git` entry, whether a directory OR a gitdir-pointer
+ *   FILE (git worktrees and submodules), matching the project family's repo test
+ *   (`existsSync(<dir>/.git)`, as `adopt`/`wiring` use). Exactly what
+ *   {@link planWorkspaceView}'s `toCreate` produces. A stray of this kind is prunable.
+ * - `broken`: a relative target that does not resolve on disk (e.g. the repo was
+ *   moved/deleted). Reported, never auto-pruned (we cannot confirm it was ours).
+ * - `non-repo`: a relative target that resolves to a non-repository path (a file,
+ *   or a directory without `.git`). Reported, never auto-pruned.
+ * - `absolute`: an absolute target. basou never writes absolute view links, so it
+ *   is not ours. Reported, never auto-pruned.
+ *
+ * The caller filters out the view's OWN instruction-file symlinks (e.g. a top-level
+ * `AGENTS.md`/`CLAUDE.md`) before classifying, so they never surface as strays.
+ */
+type ExistingViewLink = {
+    name: string;
+    target: string;
+    kind: "repo" | "broken" | "non-repo" | "absolute";
+};
+/**
+ * A view symlink not tied to any current roster repo that was NOT auto-pruned
+ * because we could not confirm it is a basou-generated repo link. Surfaced for
+ * the operator to resolve by hand; never removed.
+ */
+type ViewStrayUnknown = {
+    name: string;
+    target: string;
+    reason: "broken" | "non-repo" | "absolute";
+};
+type WorkspaceViewPlan = {
+    /** The view symlinks to create (the `missing` ones), as name + relative target. */
+    toCreate: {
+        name: string;
+        target: string;
+    }[];
+    /** Existing entries that block generation and are left untouched. */
+    conflicts: ViewConflict[];
+    /** Distinct repos colliding on one view link name (not auto-wired). */
+    collisions: ViewCollision[];
+    /** Roster repo paths that cannot be aggregated: unresolved on disk, or resolving to the view itself. */
+    unreachable: string[];
+    /**
+     * Stray basou-generated repo links to remove: a view symlink whose name is not
+     * a current roster repo and whose relative target follows to a git repository.
+     * Removed only under `--prune` (its own opt-in, separate from `--apply`).
+     */
+    toPrune: {
+        name: string;
+        target: string;
+    }[];
+    /**
+     * Stray view symlinks not tied to any roster repo that we did NOT recognize as
+     * a basou-generated repo link (broken, non-repo, or absolute target). Reported,
+     * never auto-pruned.
+     */
+    strayUnknown: ViewStrayUnknown[];
+    /** Count of repos whose view link is already correct (for the report). */
+    correctCount: number;
+    /**
+     * True only when nothing needs creating, there are no conflicts, no collisions,
+     * no unreachable repos, AND no strays (prunable or unknown) — so a clean "view
+     * in sync" verdict is never claimed while a repo was blocked, ambiguous, could
+     * not be resolved, or the view still carries an entry the roster no longer backs.
+     */
+    ok: boolean;
+};
+/**
+ * Compute the {@link WorkspaceViewPlan} from per-repo facts. For each declared,
+ * reachable, non-colliding repo: a `missing` view link becomes a create, a
+ * `mismatch`/`occupied`/`blocked` link becomes a {@link ViewConflict} (never a
+ * create — we do not overwrite), and a `correct` link is counted. The view
+ * aggregates exactly the DECLARED roster — the anchor is aggregated when present
+ * as its `.` entry (which `adopt` always adds) and, unlike the instruction
+ * symlinks, is NOT skipped; it is not implicitly injected when absent (the roster
+ * is the single source of truth). An unresolvable repo is `unreachable`, and two
+ * distinct repos sharing a basename are a {@link ViewCollision} (neither
+ * auto-wired).
+ *
+ * Stray detection (the inverse of generation): given the entries actually present
+ * in the view (`existing`), any symlink whose name is NOT owned by a declared
+ * roster repo is a stray. A stray classified `repo` (a relative target following to
+ * a git repository — basou's own generation shape) goes to `toPrune` (removed only
+ * under the separate `--prune` opt-in); a stray we cannot confirm is ours (broken,
+ * non-repo, or absolute target) goes to `strayUnknown` (reported, never removed).
+ *
+ * Ownership (what is NEVER a stray): a name is owned if it is the link name of a
+ * reachable roster repo OR appears in `rosterNames` — the basenames of EVERY
+ * declared roster entry, supplied independent of reachability. The reachability-
+ * independent set is load-bearing: a roster repo whose path transiently fails to
+ * resolve (an unmounted volume, a mid-edit symlinked parent, an uncloned sibling)
+ * still owns its view link name, so its live link is never mislabeled a stray and
+ * pruned. (A roster repo's link reached under a DIFFERENT name — e.g. an aliased
+ * roster path — is excluded by the caller before it reaches `existing`, by matching
+ * the link's resolved target against the roster's resolved repos.) `existing` and
+ * `rosterNames` default to empty, so a caller that does not scan the view gets the
+ * original create-only plan.
+ *
+ * Robustness (mirroring the instruction-symlink planner):
+ * - Facts are deduped by normalized path (a repo declared twice yields one link,
+ *   never a duplicate `symlinkSync` → EEXIST or a duplicate report entry).
+ * - `ok` is true only when there is genuinely nothing to do, every repo was
+ *   resolvable and unambiguous, and the view carries no stray.
+ */
+declare function planWorkspaceView(facts: ViewRepoFact[], existing?: ExistingViewLink[], rosterNames?: string[]): WorkspaceViewPlan;
+
 /**
  * Schema version of the on-disk Basou v0.1 formats these JSON Schemas describe.
  * It tracks {@link SchemaVersionSchema} (the `schema_version` field), NOT the
@@ -3668,6 +4642,126 @@ type ReportRendererResult = {
  */
 declare function renderReport(input: ReportRendererInput): Promise<ReportRendererResult>;
 
+/**
+ * Review-gap surfacer: a read-only, advisory check for the "external
+ * adversarial review before commit" protocol. For each unit of work that landed
+ * commits, it asks whether a CROSS-MODEL review session (a different vendor than
+ * the one that wrote the code — here: Codex) actually examined that repo's diff
+ * before the commit.
+ *
+ * Hard design rule, learned from killing the naive time-window v1 (which
+ * false-cleared the very omission that motivated this): it NEVER emits a
+ * confident "reviewed / clear" verdict. Temporal proximity is not binding. The
+ * worst failure mode is falsely reassuring the operator that a protocol was
+ * followed when it was not, so this surfaces SUSPICION and leaves the final
+ * binding to a human:
+ *
+ *  - `omission`      no cross-model review of this repo in the preceding window.
+ *  - `near_unbound`  a review session was nearby but did not examine this repo's
+ *                    diff or any changed file (the exact class naive v1 cleared).
+ *  - `candidate`     a review session examined this repo's diff / overlapping
+ *                    files — listed for the human to confirm it covered THIS
+ *                    change. NOT an automatic pass.
+ *  - `unknown`       the repo or time could not be derived; abstain rather than
+ *                    guess (an abstention is never counted as a clear).
+ *
+ * It reads only captured provenance and writes nothing.
+ */
+type ReviewGapVerdict = "omission" | "near_unbound" | "candidate" | "unknown";
+/** A cross-model review session cited as (possibly) covering a unit of work. */
+type CitedReview = {
+    sessionId: string;
+    /** The session ran `git diff` / `git show` in the repo (examined the diff). */
+    examinedDiff: boolean;
+    /** Basenames of files the session read/inspected in the repo (capped). */
+    files: string[];
+    endedAt: string | null;
+};
+/** One unit of work (a committing session's commits in one repo) and its verdict. */
+type ReviewGapUnit = {
+    repo: string;
+    /** The session whose commits form this unit. */
+    sessionId: string;
+    commitCount: number;
+    firstCommitAt: string | null;
+    lastCommitAt: string | null;
+    verdict: ReviewGapVerdict;
+    /** For `candidate` / `near_unbound`: the review sessions considered. */
+    reviews: CitedReview[];
+};
+type ReviewGapRepoSummary = {
+    repo: string;
+    units: number;
+    omissionUnits: number;
+    nearUnboundUnits: number;
+    candidateUnits: number;
+    unknownUnits: number;
+};
+type ReviewGapsSummary = {
+    generatedAt: string;
+    windowHours: number;
+    /** Repos the scope was restricted to, or null when every repo was considered. */
+    scope: string[] | null;
+    repos: ReviewGapRepoSummary[];
+    /** Units WITHOUT a binding review trail (omission + near_unbound), recent-first. */
+    gaps: ReviewGapUnit[];
+    /** Units WITH a review candidate, recent-first (surfaced for confirmation). */
+    candidates: ReviewGapUnit[];
+    /** Units whose repo/time could not be derived from the captured command; abstained, not cleared. */
+    unknowns: ReviewGapUnit[];
+    /** Newest captured commit considered; commits not yet imported are invisible. */
+    newestCommitAt: string | null;
+};
+/**
+ * Normalize a path to a stable BINDING key: the canonical full path (NOT just a
+ * basename), so a commit in `/u/projects/basou` and a review in
+ * `/u/projects/basou` bind, while a same-named checkout elsewhere
+ * (`/tmp/x/basou`) does not.
+ *
+ * A workspace "view" reaches sibling repos through symlinks
+ * (`<view>/<repo> -> ../<repo>`), and commits are often run with
+ * `cd <view>/<repo>`. To collapse the view-routed path and the direct path to
+ * one key REGARDLESS of the view directory's name, the path is resolved with
+ * realpath (which also unifies platform aliases such as macOS `/tmp` ->
+ * `/private/tmp`). Only absolute paths are resolved; a relative `cd ../x` target
+ * would realpath against the wrong base, so it is left to the fallback.
+ *
+ * A resolved path is accepted as a key only when it is an actual git repo root
+ * (contains `.git`); a real but non-repo directory (a view root, `/tmp`, a
+ * scratch dir) returns null so the caller abstains (`unknown`) rather than
+ * mislabeling it a repo. When realpath cannot resolve the path (e.g. a historical
+ * capture whose repo has since moved), it FALLS BACK to a string heuristic that
+ * collapses a `*-workspace`-named view and rejects the view root itself. Returns
+ * null for a non-repo / view root, an unexpanded shell var, or empty input.
+ *
+ * The realpath / `.git` probes are the only filesystem I/O this otherwise
+ * string-pure key function performs, and their results are cached for the
+ * process lifetime.
+ */
+declare function normalizeRepoPath(p: string | null | undefined): string | null;
+/**
+ * Short repo key (the final path segment) for DISPLAY and `--scope` matching.
+ * Binding uses {@link normalizeRepoPath} to avoid basename collisions; this is
+ * only the human-facing label.
+ */
+declare function normalizeRepoKey(p: string | null | undefined): string | null;
+type ReviewGapsInput = {
+    paths: BasouPaths;
+    /** ISO "now"; basis for `generatedAt`. */
+    nowIso: string;
+    /** Restrict to these repo keys (e.g. ["basou"]); omit/empty = every repo seen. */
+    scope?: string[];
+    /** Coarse pre-filter window before a commit to look for a review; default 24h. */
+    windowHours?: number;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+};
+/**
+ * Compute the {@link ReviewGapsSummary} for a workspace. Read-only: reads
+ * captured sessions / events and writes nothing.
+ */
+declare function findReviewGaps(input: ReviewGapsInput): Promise<ReviewGapsSummary>;
+
 /**
  * Internal abstraction over child-process execution.
  *
@@ -4205,4 +5299,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, type PrefixedId, type ProcessRunner, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type ReplayOptions, type ReplayWarning, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type RiskLevel, RiskLevelSchema, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, finalizeSessionYaml, findErrorCode, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isImportDerivedSource, isLazyExpired, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, overwriteYamlFile, parseDuration, parseMarkers, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, renderDecisions, renderHandoff, renderOrientation, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, tryRemoteUrl, ulid, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type ProcessRunner, type PublishKind, type PublishTarget, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoLanguage, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLinkState, type ViewRepoFact, type ViewStrayUnknown, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, finalizeSessionYaml, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };