@basou/core 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -678,6 +678,7 @@ type BasouPaths = {
         readonly status: string;
         readonly handoff: string;
         readonly decisions: string;
+        readonly orientation: string;
     };
 };
 /**
@@ -2031,6 +2032,29 @@ type GitSnapshot = Omit<GitSnapshotEvent, "schema_version" | "id" | "session_id"
  * path; native errors are kept on `error.cause` for verbose surfacing.
  */
 declare function resolveRepositoryRoot(cwd: string): Promise<string>;
+/**
+ * Resolve the repository root that owns the `.basou/` store for `cwd`, with a
+ * fallback for agents-workspace "view" directories. A workspace view (e.g.
+ * `~/projects/foo-workspace`) is intentionally OUTSIDE git and holds no `.basou/`
+ * of its own; it aggregates sibling repos through symlinks (`foo-planning ->
+ * ../foo-planning`). Running `basou orient` / `refresh` from there would
+ * otherwise die with "Not a git repository" even though the view IS the
+ * operator's daily cwd.
+ *
+ * Resolution:
+ *  1. If `cwd` is inside a git repo, return its toplevel (unchanged behavior).
+ *  2. Otherwise inspect `cwd`'s direct symlinks; if exactly one points at a
+ *     directory that has a `.basou/` store, redirect to that repo (firing
+ *     `onRedirect`). Zero candidates re-throws the original "Not a git
+ *     repository"; two or more throws an ambiguity error naming them so the
+ *     operator can `cd` into the right one.
+ */
+declare function resolveBasouRepositoryRoot(cwd: string, opts?: {
+    onRedirect?: (info: {
+        via: string;
+        root: string;
+    }) => void;
+}): Promise<string>;
 /**
  * Read `remote.origin.url` from the local repository config. Returns
  * `undefined` if the remote is unset, the value is empty, or the lookup
@@ -2908,6 +2932,13 @@ declare function renderHandoff(input: HandoffRendererInput): Promise<HandoffRend
  */
 declare function parseDuration(input: string): number;
 
+/**
+ * Coarse human duration from milliseconds: "3h 05m" / "12m 30s" / "8s".
+ * Shared by the work-stats surfaces (`basou stats`, `basou session show`) and
+ * the report renderer so they format identically.
+ */
+declare function formatDurationMs(ms: number): string;
+
 /**
  * Resolve a possibly-truncated session id prefix to a full session id by
  * scanning `<paths.sessions>/`. Existing message contract (carried over
@@ -3019,121 +3050,155 @@ type SanitizeRelatedFilesResult = {
  */
 declare function sanitizeRelatedFiles(paths: ReadonlyArray<string>, opts: SanitizePathOptions): SanitizeRelatedFilesResult;
 
-/**
- * Internal abstraction over child-process execution.
- *
- * The v0.1 implementation is intentionally minimal:
- * - Optional UTF-8 stdout/stderr capture (`capture: "buffer"`, default) or
- *   pass-through to the parent's stdio (`capture: "none"`).
- * - No stream callbacks for partial chunks.
- * - No event emission. Callers wire any event flow separately.
- *
- * The boundary is internal: ProcessRunner is not part of the public
- * adapter surface. Adapters do not import or instantiate it directly;
- * CLI / Core orchestration owns construction and invocation.
- */
-/**
- * Output capture mode.
- *
- * - `"buffer"` (default): pipe stdout/stderr to the runner and accumulate
- *   the full UTF-8 string into {@link RunResult}.
- * - `"none"`: inherit the parent's stdio. The child writes directly to the
- *   parent terminal in real time and {@link RunResult.stdout} /
- *   {@link RunResult.stderr} are empty strings. `stdin` cannot be combined
- *   with `"none"` because the child has no writable stdin pipe.
- */
-type CaptureMode = "buffer" | "none";
-type RunOptions = {
-    /**
-     * Working directory for the child process. Required: callers resolve
-     * the workspace root themselves; the runner does not validate cwd
-     * existence and surfaces native spawn errors via classification.
-     */
-    readonly cwd: string;
-    /**
-     * Environment variables for the child. When omitted, the parent's
-     * `process.env` is inherited verbatim. Callers wanting a sanitized
-     * environment must build it explicitly.
-     */
-    readonly env?: NodeJS.ProcessEnv;
-    /**
-     * External cancellation. Aborting the signal triggers a two-stage
-     * kill (SIGTERM, then SIGKILL after a short grace period).
-     */
-    readonly signal?: AbortSignal;
-    /**
-     * Internal timeout in milliseconds. Must be a positive finite number.
-     * Triggers the same two-stage kill as `signal`.
-     */
-    readonly timeout_ms?: number;
-    /**
-     * Optional input written to the child's stdin. The pipe is closed
-     * after the value is written. Incompatible with `capture: "none"`.
-     */
-    readonly stdin?: string | Buffer;
+/** Input contract for {@link renderOrientation} and {@link summarizeOrientation}. */
+type OrientationRendererInput = {
+    paths: BasouPaths;
+    /** ISO timestamp embedded in the header AND used as "now" for freshness + suspect classification. */
+    nowIso: string;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+    onTaskSkip?: (taskId: string, reason: TaskSkipReason) => void;
+    /** Maximum related_files entries to display before `... +N more`. Default 10. */
+    relatedFilesLimit?: number;
     /**
-     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
+     * Result of a read-only dry-run staleness probe (sessions a `basou refresh`
+     * would add or update), computed by the CLI which holds the import context.
+     * Drives the plain "これは最新か" verdict. `null` / omitted = not probed, so
+     * the verdict says it cannot confirm freshness rather than claiming current.
      */
-    readonly capture?: CaptureMode;
+    staleness?: {
+        newSessions: number;
+        updatedSessions: number;
+        unverifiableSessions?: number;
+    } | null;
     /**
-     * Invoked synchronously immediately after the child has been spawned,
-     * before the runner waits for completion. Callers use this to retain a
-     * reference for parent-side cleanup (e.g. an `exit` hook that SIGKILLs
-     * the child if the parent is forcibly terminated). The runner takes no
-     * action if the callback throws.
+     * Append the raw freshness telemetry (ISO timestamp, per-source counts, source
+     * roots, suspect count) under the plain verdict. Off by default so the section
+     * reads as a verdict for a supervisor, not developer diagnostics.
      */
-    readonly onSpawn?: (child: ChildProcess) => void;
+    verbose?: boolean;
 };
-type RunResult = {
-    readonly command: string;
-    readonly args: readonly string[];
-    readonly cwd: string;
-    /** `null` when the process was killed by a signal. */
-    readonly exit_code: number | null;
-    readonly signal: NodeJS.Signals | null;
-    readonly stdout: string;
-    readonly stderr: string;
-    /** ISO 8601 timestamp captured before spawn. */
-    readonly started_at: string;
-    /** ISO 8601 timestamp captured on the `close` event. */
-    readonly ended_at: string;
-    readonly duration_ms: number;
-    readonly pid: number | null;
+type OrientationRendererResult = {
+    /** Generated body. orientation.md is overwritten whole (no markers, gitignored). */
+    body: string;
+    sessionCount: number;
+    pendingApprovalsCount: number;
+    suspectCount: number;
+    /** Tasks whose status is `planned` or `in_progress`. */
+    inFlightTaskCount: number;
+    decisionCount: number;
 };
-type ProcessRunner = {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+type DecisionRecord = {
+    decisionId: string;
+    title: string;
+    occurredAt: string;
+};
+type PendingApproval = {
+    id: string;
+    risk: string;
+    kind: string;
+    reason: string;
+    sessionId: string;
+    createdAt: string;
+    expired: boolean;
+};
+type InFlightTask = {
+    id: string;
+    title: string;
+    status: string;
+    linkedSessions: number;
+};
+type PlannedTask = {
+    id: string;
+    title: string;
+};
+type SuspectSession = {
+    sessionId: string;
+    status: string;
+    reason: SuspectReason | null;
+};
+type LatestSession = {
+    sessionId: string;
+    label: string | null;
+    status: string;
+};
+type SourceCount = {
+    kind: string;
+    count: number;
 };
-
 /**
- * Spawn-based ProcessRunner implementation.
+ * The vendor-neutral, serializable structured summary behind orientation. This
+ * is the single source of the four orientation questions (where am I now / what
+ * is in flight / where am I heading / is this current). {@link renderOrientation}
+ * formats it into markdown; programmatic consumers (e.g. a multi-workspace
+ * portfolio view) read it directly without parsing prose.
  *
- * Behavior:
- * - `shell: false` and `detached: false`. The process group is not
- *   detached, but the OS does not guarantee the child is reaped when
- *   the parent terminates abruptly; callers handle SIGINT/SIGTERM/exit
- *   hooks themselves.
- * - `capture: "buffer"` (default): `stdio: ['pipe', 'pipe', 'pipe']`,
- *   stdout / stderr are decoded as UTF-8 and accumulated as full
- *   strings (no streaming callbacks).
- * - `capture: "none"`: `stdio: ['inherit', 'inherit', 'inherit']`, the
- *   child writes directly to the parent terminal in real time and
- *   `RunResult.stdout` / `stderr` are empty strings. `stdin` is
- *   incompatible with this mode (the child has no writable stdin pipe)
- *   and the combination is rejected before spawn.
- * - `timeout_ms` and `AbortSignal` both trigger a two-stage kill:
- *   `SIGTERM`, then `SIGKILL` after `DEFAULT_KILL_GRACE_MS` (5_000 ms).
- * - A non-zero `exit_code` does not throw; it is returned via
- *   `RunResult`. Spawn-time errors throw with a pathless message and
- *   the original error attached as `cause`.
+ * It carries STRUCTURED FACTS only — the pending-approval list with risk/reason,
+ * suspect sessions, in-flight task linkage, capture freshness/coverage, the
+ * latest decision. It deliberately holds NO work-stats (volume / active time /
+ * tokens) and NO per-agent scorecards, productivity, or utilization metrics:
+ * orientation shows product state, not surveillance of the fleet.
+ */
+type OrientationSummary = {
+    /** ISO "now"; the header timestamp and the basis for freshness/suspect classification. */
+    generatedAt: string;
+    /** All captured sessions (archived included), matching the count line. */
+    sessionCount: number;
+    /** Newest non-archived, non-import session ("where am I now"); null when none. */
+    latestSession: LatestSession | null;
+    /** Most recent `decision_recorded` across all sessions; null when none. */
+    latestDecision: DecisionRecord | null;
+    decisionCount: number;
+    /** related_files of the latest session, deduped + sorted + capped at the display limit. */
+    relatedFiles: {
+        displayed: string[];
+        overflow: number;
+    };
+    /** Tasks whose status is `planned` or `in_progress`. */
+    inFlightTasks: InFlightTask[];
+    /** Tasks whose status is `planned` ("where am I heading"). */
+    plannedTasks: PlannedTask[];
+    pendingApprovals: PendingApproval[];
+    suspects: SuspectSession[];
+    freshness: {
+        /** started_at of the newest non-archived session, or null when none captured. */
+        newestStartedAt: string | null;
+        /** source.kind of the newest non-archived session, or null when none captured. */
+        newestSource: 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. */
+        sourceRoots: string[] | null;
+    };
+};
+/**
+ * Gather the structured orientation facts for a workspace. Read-only and runs
+ * NO imports: freshness reflects already-captured state, so a stale capture is
+ * visible rather than silently refreshed (run `basou refresh` to re-import).
  *
- * Error message contract: messages never include `cwd` or absolute
- * command paths. The original errno (and any nested wrapping) is
- * preserved on `Error.cause`, allowing callers to classify with
- * `findErrorCode` when needed.
+ * Returns a fully serializable {@link OrientationSummary}. See its docstring for
+ * the positioning constraint (no work-stats, no surveillance metrics).
  */
-declare class ChildProcessRunner implements ProcessRunner {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
-}
+declare function summarizeOrientation(input: OrientationRendererInput): Promise<OrientationSummary>;
+/**
+ * Render `.basou/orientation.md`: a point-in-time "current position" view for a
+ * supervisor who delegated execution to AI agents. Unlike `handoff.md` (a
+ * session-resume narrative) this answers four orientation questions —
+ * where am I now / what is in flight / where am I heading / is this current —
+ * and deliberately leads with STRUCTURED FACTS an LLM cannot reliably derive
+ * from raw transcripts (the
+ * pending-approval list with risk/reason, suspect sessions, in-flight task
+ * linkage, capture freshness/coverage) rather than prose synthesis.
+ *
+ * The renderer is read-only and runs NO imports: the freshness section reflects
+ * already-captured state, so a stale capture is visible rather than silently
+ * refreshed (use `basou refresh` to re-import). It must never emit per-agent
+ * scorecards, productivity, or utilization metrics — orientation shows product
+ * state, not surveillance of the fleet.
+ *
+ * Formatting only: the facts come from {@link summarizeOrientation}.
+ */
+declare function renderOrientation(input: OrientationRendererInput): Promise<OrientationRendererResult>;
 
 /**
  * Schema version of the on-disk Basou v0.1 formats these JSON Schemas describe.
@@ -3472,10 +3537,262 @@ declare function computeWorkStats(input: WorkStatsInput): Promise<WorkStatsResul
  */
 declare function sessionWorkStatsFromEvents(sessionId: string, inner: Session["session"], events: ReadonlyArray<Event>, now: Date, eventsUnreadable?: boolean): SessionWorkStats;
 
+type ReportRendererInput = {
+    paths: BasouPaths;
+    /** ISO timestamp stamped into the report header and used as the clock. */
+    nowIso: string;
+    /** Optional subject line surfaced in the report title. */
+    title?: string;
+    /**
+     * IANA timezone passed through to {@link computeWorkStats} (it labels the
+     * time figures with the zone). The CLI omits this (host default); tests and
+     * the SDK pass a fixed value for deterministic output. [Codex #5]
+     */
+    timeZone?: string;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+    onTaskSkip?: (taskId: string, reason: TaskSkipReason) => void;
+};
+type ReportSessionItem = {
+    id: string;
+    label: string | null;
+    status: SessionStatus;
+    source: SessionSourceKind;
+    startedAt: string;
+    activeMs: number;
+    outputTokens: number;
+};
+type ReportDecisionItem = {
+    id: string;
+    title: string;
+    occurredAt: string;
+};
+type ReportTaskItem = {
+    id: string;
+    title: string;
+    status: TaskStatus;
+};
+type ReportApprovalItem = {
+    id: string;
+    reason: string;
+    status: ApprovalStatus;
+    riskLevel: RiskLevel;
+};
+type TaskStatusCount = {
+    status: TaskStatus;
+    count: number;
+};
+/**
+ * Curated, purpose-built structured shape behind `basou report generate
+ * --json`. Deliberately NOT the full {@link WorkStatsResult} — report's JSON
+ * stays a stable contract decoupled from the stats schema. Field names avoid
+ * the word "billable": a report is a neutral work-explanation export, not a
+ * billing artifact. [Codex #2]
+ */
+type ReportData = {
+    generatedAt: string;
+    title?: string;
+    /** Earliest session start .. latest session end (or `now` for open sessions). */
+    period: {
+        from: string | null;
+        to: string | null;
+    };
+    sessions: {
+        total: number;
+        byStatus: StatusCount[];
+        items: ReportSessionItem[];
+    };
+    volume: {
+        outputTokens: number;
+        reasoningTokens: number;
+        commandCount: number;
+        fileChangedCount: number;
+        decisionCount: number;
+        tokensAvailable: boolean;
+    };
+    time: {
+        activeMs: number;
+        machineActiveMs: number;
+        machineAvailable: boolean;
+        spanMs: number;
+        commandTimeMs: number;
+        timeZone: string;
+    };
+    decisions: {
+        count: number;
+        items: ReportDecisionItem[];
+    };
+    approvals: {
+        pending: number;
+        approved: number;
+        rejected: number;
+        expired: number;
+        items: ReportApprovalItem[];
+    };
+    tasks: {
+        total: number;
+        byStatus: TaskStatusCount[];
+        items: ReportTaskItem[];
+    };
+    /** Union of related files across non-`import` sessions (full; markdown truncates). */
+    changedFiles: string[];
+    integrity: {
+        total: number;
+        verified: number;
+        unchained: number;
+        empty: number;
+        incomplete: number;
+        in_progress: number;
+        tampered: number;
+        /** Session ids whose chain is `tampered`, surfaced for follow-up. */
+        tamperedSessions: string[];
+    };
+};
+type ReportRendererResult = {
+    body: string;
+    data: ReportData;
+};
+/**
+ * Render a neutral "work report" — a point-in-time export that explains the
+ * work captured in a workspace: how much, what was decided / approved /
+ * undertaken, which files changed, and whether the local provenance is
+ * internally consistent. It composes existing read primitives only and writes
+ * nothing; the caller chooses where `body` goes (stdout / a file) and whether
+ * to emit the structured `data` as JSON.
+ *
+ * Warning surfaces mirror the sibling renderers: `loadSessionEntries` (suspect
+ * classification) and the decision-aggregation replay (with the same
+ * unreadable-skip wrapper as `decisions-renderer.ts`) report through the
+ * callbacks. {@link computeWorkStats} runs SILENTLY here — it re-reads the same
+ * sessions/events, so surfacing its warnings too would double-emit. [Codex #6]
+ */
+declare function renderReport(input: ReportRendererInput): Promise<ReportRendererResult>;
+
+/**
+ * Internal abstraction over child-process execution.
+ *
+ * The v0.1 implementation is intentionally minimal:
+ * - Optional UTF-8 stdout/stderr capture (`capture: "buffer"`, default) or
+ *   pass-through to the parent's stdio (`capture: "none"`).
+ * - No stream callbacks for partial chunks.
+ * - No event emission. Callers wire any event flow separately.
+ *
+ * The boundary is internal: ProcessRunner is not part of the public
+ * adapter surface. Adapters do not import or instantiate it directly;
+ * CLI / Core orchestration owns construction and invocation.
+ */
+/**
+ * Output capture mode.
+ *
+ * - `"buffer"` (default): pipe stdout/stderr to the runner and accumulate
+ *   the full UTF-8 string into {@link RunResult}.
+ * - `"none"`: inherit the parent's stdio. The child writes directly to the
+ *   parent terminal in real time and {@link RunResult.stdout} /
+ *   {@link RunResult.stderr} are empty strings. `stdin` cannot be combined
+ *   with `"none"` because the child has no writable stdin pipe.
+ */
+type CaptureMode = "buffer" | "none";
+type RunOptions = {
+    /**
+     * Working directory for the child process. Required: callers resolve
+     * the workspace root themselves; the runner does not validate cwd
+     * existence and surfaces native spawn errors via classification.
+     */
+    readonly cwd: string;
+    /**
+     * Environment variables for the child. When omitted, the parent's
+     * `process.env` is inherited verbatim. Callers wanting a sanitized
+     * environment must build it explicitly.
+     */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * External cancellation. Aborting the signal triggers a two-stage
+     * kill (SIGTERM, then SIGKILL after a short grace period).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Internal timeout in milliseconds. Must be a positive finite number.
+     * Triggers the same two-stage kill as `signal`.
+     */
+    readonly timeout_ms?: number;
+    /**
+     * Optional input written to the child's stdin. The pipe is closed
+     * after the value is written. Incompatible with `capture: "none"`.
+     */
+    readonly stdin?: string | Buffer;
+    /**
+     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
+     */
+    readonly capture?: CaptureMode;
+    /**
+     * Invoked synchronously immediately after the child has been spawned,
+     * before the runner waits for completion. Callers use this to retain a
+     * reference for parent-side cleanup (e.g. an `exit` hook that SIGKILLs
+     * the child if the parent is forcibly terminated). The runner takes no
+     * action if the callback throws.
+     */
+    readonly onSpawn?: (child: ChildProcess) => void;
+};
+type RunResult = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** `null` when the process was killed by a signal. */
+    readonly exit_code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** ISO 8601 timestamp captured before spawn. */
+    readonly started_at: string;
+    /** ISO 8601 timestamp captured on the `close` event. */
+    readonly ended_at: string;
+    readonly duration_ms: number;
+    readonly pid: number | null;
+};
+type ProcessRunner = {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+};
+
+/**
+ * Spawn-based ProcessRunner implementation.
+ *
+ * Behavior:
+ * - `shell: false` and `detached: false`. The process group is not
+ *   detached, but the OS does not guarantee the child is reaped when
+ *   the parent terminates abruptly; callers handle SIGINT/SIGTERM/exit
+ *   hooks themselves.
+ * - `capture: "buffer"` (default): `stdio: ['pipe', 'pipe', 'pipe']`,
+ *   stdout / stderr are decoded as UTF-8 and accumulated as full
+ *   strings (no streaming callbacks).
+ * - `capture: "none"`: `stdio: ['inherit', 'inherit', 'inherit']`, the
+ *   child writes directly to the parent terminal in real time and
+ *   `RunResult.stdout` / `stderr` are empty strings. `stdin` is
+ *   incompatible with this mode (the child has no writable stdin pipe)
+ *   and the combination is rejected before spawn.
+ * - `timeout_ms` and `AbortSignal` both trigger a two-stage kill:
+ *   `SIGTERM`, then `SIGKILL` after `DEFAULT_KILL_GRACE_MS` (5_000 ms).
+ * - A non-zero `exit_code` does not throw; it is returned via
+ *   `RunResult`. Spawn-time errors throw with a pathless message and
+ *   the original error attached as `cause`.
+ *
+ * Error message contract: messages never include `cwd` or absolute
+ * command paths. The original errno (and any nested wrapping) is
+ * preserved on `Error.cause`, allowing callers to classify with
+ * `findErrorCode` when needed.
+ */
+declare class ChildProcessRunner implements ProcessRunner {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+}
+
 type AppendBasouGitignoreResult = {
     /** True if the block was appended (or the file was newly created). */
     readonly appended: boolean;
 };
+/** Options for {@link appendBasouGitignore}. */
+type AppendBasouGitignoreOptions = {
+    /** Write a `.basou/` full-exclude block instead of the default ignore+commit block. */
+    readonly localOnly?: boolean;
+};
 /**
  * Append Basou's default `.gitignore` block to `repositoryRoot/.gitignore`.
  *
@@ -3483,11 +3800,15 @@ type AppendBasouGitignoreResult = {
  * standard ignore + commit recommendations). Callers must pass an absolute
  * path to a Git repository root.
  *
+ * With `options.localOnly`, a `.basou/` full-exclude block is written instead
+ * of the default ignore+commit block (the trail is kept out of version
+ * control). The default (no options) is unchanged.
+ *
  * Behavior:
- * - If `.gitignore` does not exist, it is created with the Basou block.
- * - If a line starting with `# Basou - default ignore` is already present,
- *   the file is left untouched and `appended: false` is returned
- *   (idempotent).
+ * - If `.gitignore` does not exist, it is created with the chosen Basou block.
+ * - If a `# Basou - default ignore` marker OR a standalone `.basou/` exclude
+ *   line is already present, the file is left untouched and `appended: false`
+ *   is returned (idempotent across both modes).
  * - If `.gitignore` is a symlink, the link is followed and the target file
  *   is updated. Symlinks are not rejected.
  *
@@ -3495,7 +3816,7 @@ type AppendBasouGitignoreResult = {
  * (`Failed to read .gitignore` / `Failed to write .gitignore`) and the
  * original native error attached as `cause`.
  */
-declare function appendBasouGitignore(repositoryRoot: string): Promise<AppendBasouGitignoreResult>;
+declare function appendBasouGitignore(repositoryRoot: string, options?: AppendBasouGitignoreOptions): Promise<AppendBasouGitignoreResult>;
 
 /**
  * The two lock scopes basou uses. `task` guards the read-modify-write window
@@ -3884,4 +4205,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 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 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 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, 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, 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, renderWithMarkers, replayEvents, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, tryRemoteUrl, ulid, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+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 };