@basou/core 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -2,369 +2,208 @@ import { z } from 'zod';
 import { ChildProcess } from 'node:child_process';
 
 /**
- * Allowed ID type prefixes for Basou entities.
- *
- * Frozen at runtime so that mutating the exported array cannot diverge from
- * the validation set used internally. The single source of truth for both
- * the `IdPrefix` type and runtime prefix checks.
+ * Static metadata identifying the claude-code adapter as the session source.
+ * Consumed by the CLI orchestration when populating `session.yaml.source`
+ * and event `source` fields. The literal `kind` is part of the wire format
+ * defined by the session schema; do not change without coordinated schema
+ * migration.
  */
-declare const ID_PREFIXES: readonly ["ws", "task", "ses", "evt", "appr", "decision"];
+declare const claudeCodeAdapterMetadata: {
+    readonly kind: "claude-code-adapter";
+    readonly version: "0.1.0";
+};
 /**
- * Type prefix used for Basou entity IDs.
- * Format: `<prefix>_<26-char ULID>`, e.g. `ws_01HXABCDEF1234567890ABCDEF`.
+ * Lookup predicate used by {@link resolveClaudeCodeCommand} to decide
+ * whether a candidate executable is reachable on PATH. Exposed as a
+ * parameter so tests can substitute a deterministic mock; production
+ * callers should omit it and rely on the default `which`-based lookup.
  */
-type IdPrefix = (typeof ID_PREFIXES)[number];
+type CommandLookup = (command: string) => Promise<boolean>;
 /**
- * A Basou entity ID as a template literal type.
+ * Resolve the Claude Code CLI executable name. Tries `claude-code` first
+ * and falls back to `claude`; the first candidate found on PATH wins.
  *
- * `PrefixedId<"ses">` narrows to ``ses_${string}`` so a session schema can
- * preserve the prefix in its inferred type beyond runtime validation.
+ * Throws a fixed-message Error when neither candidate is reachable, so
+ * callers can present a single user-facing prompt to install the CLI.
+ *
+ * @throws Error("Claude Code CLI not found in PATH. Install claude-code (or claude) first.")
  */
-type PrefixedId<P extends IdPrefix = IdPrefix> = `${P}_${string}`;
+declare function resolveClaudeCodeCommand(lookup?: CommandLookup): Promise<{
+    command: string;
+}>;
 /**
- * Generate a Crockford Base32 ULID.
- *
- * The result is a 26-character, lexicographically time-sortable identifier.
- * Multiple calls within the same millisecond are strictly increasing for the
- * lifetime of the current process.
+ * Stub for the future `adapter_output` summary generator.
  *
- * NOTE: `seedTime` is forwarded to the underlying monotonic factory and is
- * NOT a deterministic seed: repeated calls with the same `seedTime` still
- * return strictly increasing values, because the factory increments its
- * internal counter on each call.
+ * The current release keeps `capture: "none"` and intentionally does
+ * not emit `adapter_output` events, so this hook has no production
+ * callers yet. The signature is committed so a later release can
+ * implement raw_ref generation without retrofitting the adapter
+ * scaffold.
  *
- * @param seedTime Optional millisecond timestamp passed to the monotonic
- *   factory. Useful for ordered generation in tests; not deterministic.
+ * @throws Error - always; not implemented in this release.
  */
-declare function ulid(seedTime?: number): string;
+declare function summarizeAdapterOutput(_stream: "stdout" | "stderr", _raw: string): string;
+
 /**
- * Generate a prefixed Basou ID, e.g. `ses_01HXABCDEF1234567890ABCDEF`.
+ * Lifecycle states of a Basou approval. The status is stored directly on
+ * the approval YAML (flat shape) so that pending → resolved transitions
+ * are atomic-move + in-place rewrites rather than schema-variant swaps.
+ */
+declare const ApprovalStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    approved: "approved";
+    rejected: "rejected";
+    expired: "expired";
+}>;
+/** Inferred runtime type for {@link ApprovalStatusSchema}. */
+type ApprovalStatus = z.infer<typeof ApprovalStatusSchema>;
+/**
+ * Schema for `.basou/approvals/{pending,resolved}/<approval_id>.yaml`.
  *
- * The return type preserves the prefix as a template literal type so that
- * downstream zod schemas can narrow an `IdPrefix` parameter through the API.
+ * The schema is intentionally flat (one shape regardless of `status`) so
+ * that pending and resolved YAMLs share the same parser. Required vs.
+ * optional semantics by status (e.g. `rejection_reason` MUST be set when
+ * `status === "rejected"`) are enforced at the CLI orchestration layer
+ * rather than here, mirroring the approval event variants in
+ * `event.schema.ts`.
  *
- * Throws if `prefix` is not one of {@link ID_PREFIXES}. The runtime guard
- * defends against JavaScript callers and casted TypeScript that bypass the
- * compile-time `IdPrefix` constraint.
+ * The `action` field is `{ kind: string }` with `passthrough()` so that
+ * adapter-defined keys (e.g. `command`, `path`, `target_url`) survive the
+ * round-trip without being stripped — matching the approval_requested
+ * event variant.
  */
-declare function prefixedUlid<P extends IdPrefix>(prefix: P): PrefixedId<P>;
+declare const ApprovalSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"0.1.0">;
+    id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+    session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+    created_at: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        rejected: "rejected";
+        expired: "expired";
+    }>;
+    risk_level: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    action: z.ZodObject<{
+        kind: z.ZodString;
+    }, z.core.$loose>;
+    reason: z.ZodString;
+    expires_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resolver: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resolved_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    note: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rejection_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link ApprovalSchema}. */
+type Approval = z.infer<typeof ApprovalSchema>;
+
 /**
- * Check whether the given string is a valid prefixed Basou ID.
+ * Absolute paths to the standard `.basou/` directory layout, derived from a
+ * given repository root. The shape mirrors the canonical `.basou/` tree
+ * (see `docs/spec/workspace.md`). `root` is the `.basou/` directory itself
+ * (i.e. `repositoryRoot/.basou`).
  *
- * Returns true only if the string has shape `<prefix>_<ULID>` where prefix is
- * one of {@link ID_PREFIXES} and the trailing 26 characters form a valid
- * Crockford Base32 ULID. Validation combines a strict shape regex (to enforce
- * the 0-7 leading char and the I/L/O/U exclusion) with the npm `ulid`
- * library's `isValid` for forward compatibility.
+ * `files` exposes the well-known top-level files inside `.basou/`. Each path
+ * is computed but not created — they are written by their respective
+ * subsystems (e.g. `writeManifest` for `manifest.yaml`).
  *
- * NOTE: This validates the prefix is known. Schemas that require a specific
- * prefix (e.g. only `ses_*` for a session ID) must add their own narrowing.
+ * All fields are deeply readonly; consumers must not mutate the returned
+ * object.
  */
-declare function isValidPrefixedId(value: string): boolean;
-
+type BasouPaths = {
+    readonly root: string;
+    readonly sessions: string;
+    readonly tasks: string;
+    readonly approvals: {
+        readonly pending: string;
+        readonly resolved: string;
+    };
+    readonly locks: string;
+    readonly logs: string;
+    readonly raw: string;
+    readonly tmp: string;
+    readonly files: {
+        readonly manifest: string;
+        readonly status: string;
+        readonly handoff: string;
+        readonly decisions: string;
+    };
+};
 /**
- * Schema version literal pinned to "0.1.0" for Basou v0.1.
- * Reused across every entity schema so inferred types narrow to the literal.
+ * Compute absolute paths to the standard `.basou/` directory layout under
+ * `repositoryRoot`. Pure: performs no I/O and is safe to call before the
+ * directory exists.
+ *
+ * @param repositoryRoot Absolute path to the git repository root (the
+ *   parent directory of `.basou/`). Caller is responsible for resolving
+ *   `process.cwd()` or running `git rev-parse --show-toplevel` upstream;
+ *   this function does not validate that the path exists or is a git
+ *   repository.
  */
-declare const SchemaVersionSchema: z.ZodLiteral<"0.1.0">;
+declare function basouPaths(repositoryRoot: string): BasouPaths;
 /**
- * ISO 8601 timestamp with explicit timezone offset (e.g. `+09:00`).
+ * Create the standard `.basou/` directory layout under `repositoryRoot`.
  *
- * The spec samples include offsets, so the default zod `.datetime()` (which
- * rejects offsets) is insufficient; `{ offset: true }` is required.
+ * Idempotent: a no-op on an already-initialized layout. Returns the resolved
+ * {@link BasouPaths} so callers can immediately use them.
+ *
+ * Throws if `repositoryRoot/.basou` (or any required subdirectory) exists
+ * but is not a directory, or if filesystem permissions prevent creation.
+ * All thrown error messages are pathless; the original native error is
+ * attached as `cause` for diagnostics.
+ *
+ * @param repositoryRoot Absolute path to the git repository root. See
+ *   {@link basouPaths} for the contract on this parameter.
  */
-declare const IsoTimestampSchema: z.ZodString;
-/** Workspace ID schema: validates `ws_<26-char ULID>`. */
-declare const WorkspaceIdSchema: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-/** Task ID schema: validates `task_<26-char ULID>`. */
-declare const TaskIdSchema: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-/** Session ID schema: validates `ses_<26-char ULID>`. */
-declare const SessionIdSchema: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-/** Event ID schema: validates `evt_<26-char ULID>`. */
-declare const EventIdSchema: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-/** Approval ID schema: validates `appr_<26-char ULID>`. */
-declare const ApprovalIdSchema: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-/** Decision ID schema: validates `decision_<26-char ULID>`. */
-declare const DecisionIdSchema: z.ZodString & z.ZodType<`decision_${string}`, string, z.core.$ZodTypeInternals<`decision_${string}`, string>>;
+declare function ensureBasouDirectory(repositoryRoot: string): Promise<BasouPaths>;
+
+/** Which side of `.basou/approvals/` an approval YAML lives on. */
+type ApprovalLocation = "pending" | "resolved";
+/** Result returned by {@link loadApproval}: the parsed approval and where it was found. */
+type LoadedApproval = {
+    approval: Approval;
+    location: ApprovalLocation;
+};
 /**
- * Risk level vocabulary fixed by the spec. Adapters MUST emit one of these
- * four values; arbitrary strings are rejected at schema parse time.
+ * Locate and load the approval YAML for `approvalId`. Searches resolved
+ * first so that a duplicated YAML (the crash-window scenario where both
+ * pending and resolved exist for the same id) returns the resolved-side
+ * record — matching the dedupe rule used by `approval list` and
+ * `resolveApprovalId`. Returns null if neither directory contains the
+ * YAML. Throws with a pathless message on read or schema-validation
+ * failure.
  */
-declare const RiskLevelSchema: z.ZodEnum<{
-    low: "low";
-    medium: "medium";
-    high: "high";
-    critical: "critical";
-}>;
-/** Inferred runtime type for {@link RiskLevelSchema}. */
-type RiskLevel = z.infer<typeof RiskLevelSchema>;
+declare function loadApproval(paths: BasouPaths, approvalId: string): Promise<LoadedApproval | null>;
 /**
- * Source attribution for events (e.g. "claude-code-adapter",
- * "git-capability", "terminal-recording", "local-cli", "human"). Free-form
- * non-empty string in v0.1; a stricter enum may be introduced post-v0.1.
+ * Enumerate approval IDs by inspecting `<id>.yaml` filenames in pending
+ * and resolved. ENOENT on either directory is treated as empty (e.g. a
+ * workspace that has no resolved approvals yet). YAML parse and schema
+ * validation are NOT performed; callers that need the parsed approval
+ * should use {@link loadApproval} per ID.
  */
-declare const EventSourceSchema: z.ZodString;
-
+declare function enumerateApprovals(paths: BasouPaths): Promise<{
+    pending: string[];
+    resolved: string[];
+}>;
 /**
- * Schema for `.basou/manifest.yaml`. The minimal manifest carries
- * schema_version, basou_version, workspace metadata, project info, enabled
- * capabilities, approval policy, adapter config, and git policy. The
- * `adapters."claude-code"` key uses a hyphen; downstream code accesses it
- * via bracket notation.
+ * Return true when an approval is in `pending` state and its `expires_at`
+ * timestamp has elapsed. Used by `basou approval list` / `show` to surface
+ * a `(expired)` label without mutating the YAML file. Approval expiry uses
+ * lazy-evaluation semantics; actual `approval_expired` event firing is
+ * deferred to a later step.
+ *
+ * `now` is taken as a parameter so a single CLI invocation can share one
+ * "now" across every record it inspects (avoids boundary races where two
+ * reads of `Date.now()` straddle an expiry instant).
  */
-declare const ManifestSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
-    basou_version: z.ZodLiteral<"0.1.0">;
-    workspace: z.ZodObject<{
-        id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-        name: z.ZodString;
-        created_at: z.ZodString;
-        updated_at: z.ZodString;
-    }, z.core.$strip>;
-    project: z.ZodObject<{
-        name: z.ZodOptional<z.ZodString>;
-        description: z.ZodOptional<z.ZodString>;
-        repository_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strip>;
-    capabilities: z.ZodObject<{
-        enabled: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>;
-    approval: z.ZodObject<{
-        required_for: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        default_risk_level: z.ZodEnum<{
-            low: "low";
-            medium: "medium";
-            high: "high";
-            critical: "critical";
-        }>;
-    }, z.core.$strip>;
-    adapters: z.ZodObject<{
-        "claude-code": z.ZodObject<{
-            enabled: z.ZodBoolean;
-            config_path: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    git: z.ZodObject<{
-        events_log: z.ZodDefault<z.ZodEnum<{
-            ignore: "ignore";
-            commit: "commit";
-        }>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-/** Inferred runtime type for {@link ManifestSchema}. */
-type Manifest = z.infer<typeof ManifestSchema>;
-
-/**
- * Schema for `.basou/status.json` — a forward-incompat cache of the current
- * workspace state.
- *
- * Each level uses `.strict()` so unknown keys are rejected rather than
- * silently stripped. A v0.1 reader that encounters a future-shape
- * `status.json` therefore fails parsing instead of returning a partially
- * empty snapshot; callers regenerate by calling `buildStatusSnapshot` +
- * `writeStatus` rather than trying to migrate.
- */
-declare const StatusSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
-    generated_at: z.ZodString;
-    workspace: z.ZodObject<{
-        id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-        name: z.ZodString;
-        basou_version: z.ZodLiteral<"0.1.0">;
-    }, z.core.$strict>;
-    directories_present: z.ZodObject<{
-        sessions: z.ZodBoolean;
-        tasks: z.ZodBoolean;
-        approvals_pending: z.ZodBoolean;
-        approvals_resolved: z.ZodBoolean;
-        logs: z.ZodBoolean;
-        raw: z.ZodBoolean;
-        tmp: z.ZodBoolean;
-    }, z.core.$strict>;
-}, z.core.$strict>;
-/** Inferred runtime type for {@link StatusSchema}. */
-type StatusSnapshot = z.infer<typeof StatusSchema>;
-
-/** Session lifecycle states. */
-declare const SessionStatusSchema: z.ZodEnum<{
-    initialized: "initialized";
-    running: "running";
-    waiting_approval: "waiting_approval";
-    completed: "completed";
-    failed: "failed";
-    interrupted: "interrupted";
-    imported: "imported";
-    archived: "archived";
-}>;
-/** Inferred runtime type for {@link SessionStatusSchema}. */
-type SessionStatus = z.infer<typeof SessionStatusSchema>;
-/** Source kind that produced the session. */
-declare const SessionSourceKindSchema: z.ZodEnum<{
-    "claude-code-adapter": "claude-code-adapter";
-    human: "human";
-    import: "import";
-    terminal: "terminal";
-}>;
-/** Inferred runtime type for {@link SessionSourceKindSchema}. */
-type SessionSourceKind = z.infer<typeof SessionSourceKindSchema>;
-/**
- * Schema for `.basou/sessions/<session_id>/session.yaml`. The minimal
- * session document carries the actual fields nested under the outer
- * `session:` key.
- */
-declare const SessionSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
-    session: z.ZodObject<{
-        id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        label: z.ZodOptional<z.ZodString>;
-        task_id: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
-        workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-        source: z.ZodObject<{
-            kind: z.ZodEnum<{
-                "claude-code-adapter": "claude-code-adapter";
-                human: "human";
-                import: "import";
-                terminal: "terminal";
-            }>;
-            version: z.ZodLiteral<"0.1.0">;
-        }, z.core.$strip>;
-        started_at: z.ZodString;
-        ended_at: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            initialized: "initialized";
-            running: "running";
-            waiting_approval: "waiting_approval";
-            completed: "completed";
-            failed: "failed";
-            interrupted: "interrupted";
-            imported: "imported";
-            archived: "archived";
-        }>;
-        working_directory: z.ZodString;
-        invocation: z.ZodObject<{
-            command: z.ZodString;
-            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            exit_code: z.ZodNullable<z.ZodNumber>;
-        }, z.core.$strip>;
-        related_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        events_log: z.ZodDefault<z.ZodString>;
-        summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-/** Inferred runtime type for {@link SessionSchema}. */
-type Session = z.infer<typeof SessionSchema>;
-
-/**
- * Task lifecycle states.
- *
- * The storage layer's `ALLOWED_TRANSITIONS` map (= source of truth in
- * `tasks.ts`) is the authoritative graph; the comment below is a snapshot.
- * `planned` reaches `done` / `cancelled` directly so tasks completed (or
- * abandoned) outside an explicit in-progress phase can close in a single
- * CLI call:
- *
- *   planned → {in_progress | done | cancelled}
- *   in_progress → {done | cancelled}
- *   done / cancelled = terminal
- *
- * Self-edges are rejected so the audit trail stays monotonic.
- */
-declare const TaskStatusSchema: z.ZodEnum<{
-    planned: "planned";
-    in_progress: "in_progress";
-    done: "done";
-    cancelled: "cancelled";
-}>;
-/** Inferred runtime type for {@link TaskStatusSchema}. */
-type TaskStatus = z.infer<typeof TaskStatusSchema>;
-/**
- * Schema for the YAML front matter of `.basou/tasks/<task_id>.md`.
- *
- * The markdown body after the front matter is intentionally NOT modelled
- * here — it is free-form user-edited content. The storage layer splits
- * the file into `task` (this schema) and `body` (the trailing string).
- */
-declare const TaskSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
-    task: z.ZodObject<{
-        id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        title: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            planned: "planned";
-            in_progress: "in_progress";
-            done: "done";
-            cancelled: "cancelled";
-        }>;
-        created_at: z.ZodString;
-        updated_at: z.ZodString;
-        workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-        created_in_session: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-/** Inferred runtime type for {@link TaskSchema}. */
-type Task = z.infer<typeof TaskSchema>;
-
-/**
- * Lifecycle states of a Basou approval. The status is stored directly on
- * the approval YAML (flat shape) so that pending → resolved transitions
- * are atomic-move + in-place rewrites rather than schema-variant swaps.
- */
-declare const ApprovalStatusSchema: z.ZodEnum<{
-    pending: "pending";
-    approved: "approved";
-    rejected: "rejected";
-    expired: "expired";
-}>;
-/** Inferred runtime type for {@link ApprovalStatusSchema}. */
-type ApprovalStatus = z.infer<typeof ApprovalStatusSchema>;
-/**
- * Schema for `.basou/approvals/{pending,resolved}/<approval_id>.yaml`.
- *
- * The schema is intentionally flat (one shape regardless of `status`) so
- * that pending and resolved YAMLs share the same parser. Required vs.
- * optional semantics by status (e.g. `rejection_reason` MUST be set when
- * `status === "rejected"`) are enforced at the CLI orchestration layer
- * rather than here, mirroring the approval event variants in
- * `event.schema.ts`.
- *
- * The `action` field is `{ kind: string }` with `passthrough()` so that
- * adapter-defined keys (e.g. `command`, `path`, `target_url`) survive the
- * round-trip without being stripped — matching the approval_requested
- * event variant.
- */
-declare const ApprovalSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
-    id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-    session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-    created_at: z.ZodString;
-    status: z.ZodEnum<{
-        pending: "pending";
-        approved: "approved";
-        rejected: "rejected";
-        expired: "expired";
-    }>;
-    risk_level: z.ZodEnum<{
-        low: "low";
-        medium: "medium";
-        high: "high";
-        critical: "critical";
-    }>;
-    action: z.ZodObject<{
-        kind: z.ZodString;
-    }, z.core.$loose>;
-    reason: z.ZodString;
-    expires_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    resolver: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    resolved_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    note: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    rejection_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-/** Inferred runtime type for {@link ApprovalSchema}. */
-type Approval = z.infer<typeof ApprovalSchema>;
-
-declare const SessionStartedEventSchema: z.ZodObject<{
+declare function isLazyExpired(approval: Approval, now: Date): boolean;
+
+declare const SessionStartedEventSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"0.1.0">;
     id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
     session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
@@ -852,51 +691,93 @@ type NoteAddedEvent = z.infer<typeof NoteAddedEventSchema>;
 /** Narrowed runtime type for the `adapter_output` event variant (.strict()). */
 type AdapterOutputEvent = z.infer<typeof AdapterOutputEventSchema>;
 
-declare const SessionInnerImportSchema: z.ZodObject<{
-    id: z.ZodOptional<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>;
-    label: z.ZodOptional<z.ZodString>;
-    task_id: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
-    workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
-    source: z.ZodObject<{
-        kind: z.ZodEnum<{
-            "claude-code-adapter": "claude-code-adapter";
-            human: "human";
-            import: "import";
-            terminal: "terminal";
-        }>;
-        version: z.ZodLiteral<"0.1.0">;
-    }, z.core.$strip>;
-    started_at: z.ZodString;
-    ended_at: z.ZodOptional<z.ZodString>;
-    status: z.ZodEnum<{
-        initialized: "initialized";
-        running: "running";
-        waiting_approval: "waiting_approval";
-        completed: "completed";
-        failed: "failed";
-        interrupted: "interrupted";
-        imported: "imported";
-        archived: "archived";
-    }>;
-    working_directory: z.ZodString;
-    invocation: z.ZodObject<{
-        command: z.ZodString;
-        args: z.ZodArray<z.ZodString>;
-        exit_code: z.ZodNullable<z.ZodNumber>;
-    }, z.core.$strip>;
-    related_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    events_log: z.ZodOptional<z.ZodString>;
-    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strict>;
 /**
- * Schema for the round-trip JSON payload accepted by `basou session import
- * --format json`. The top level is `.strict()`; unknown keys at the outer
- * envelope are rejected.
+ * Recoverable warning surfaced via {@link ReplayOptions.onWarning}. The replay
+ * generator never throws on these — it skips the offending line and continues.
+ *
+ * `partial_trailing_line` indicates the events.jsonl did not end with `\n` and
+ * the unterminated tail parsed as a complete event. The line is dropped
+ * instead of yielded so consumers cannot accidentally observe a
+ * partially-written record.
  */
-declare const SessionImportPayloadSchema: z.ZodObject<{
-    schema_version: z.ZodString;
+type ReplayWarning = {
+    kind: "partial_trailing_line";
+    line: number;
+} | {
+    kind: "malformed_json";
+    line: number;
+    cause: unknown;
+} | {
+    kind: "schema_violation";
+    line: number;
+    cause: unknown;
+};
+type ReplayOptions = {
+    /**
+     * Hook to receive recoverable warnings (partial line / malformed JSON /
+     * schema violation). When omitted, warnings are silently dropped — callers
+     * that want to surface them (e.g. CLI orchestration) MUST provide this hook.
+     */
+    onWarning?: (warning: ReplayWarning) => void;
+};
+/**
+ * Stream events from `<sessionDir>/events.jsonl` line by line.
+ *
+ * Behavior:
+ * - ENOENT or empty file: yields nothing without warning.
+ * - I/O error: throws `Error("Failed to read events.jsonl")` with the native
+ *   error attached as `cause`. The thrown message never embeds an absolute
+ *   path (pathless contract).
+ * - Trailing partial line that parses as a valid event: dropped silently when
+ *   {@link ReplayOptions.onWarning} is omitted; otherwise reported as
+ *   `partial_trailing_line`. A trailing partial line that fails JSON parsing
+ *   is reported as `malformed_json` instead.
+ * - Malformed JSON / schema violation: skipped, with the corresponding
+ *   warning when a hook is provided.
+ *
+ * Single-writer-per-session is assumed (see `event-writer.ts` JSDoc on
+ * {@link appendEvent}). Concurrent writers may interleave lines beyond
+ * `PIPE_BUF` and are not recovered here in v0.1.
+ */
+declare function replayEvents(sessionDir: string, options?: ReplayOptions): AsyncGenerator<Event, void, void>;
+/**
+ * Eager array helper: collect every event from {@link replayEvents} into
+ * memory. Convenience for callers that need the full list in one structure
+ * (e.g. `basou session show` rendering).
+ */
+declare function readAllEvents(sessionDir: string, options?: ReplayOptions): Promise<Event[]>;
+
+/** Session lifecycle states. */
+declare const SessionStatusSchema: z.ZodEnum<{
+    initialized: "initialized";
+    running: "running";
+    waiting_approval: "waiting_approval";
+    completed: "completed";
+    failed: "failed";
+    interrupted: "interrupted";
+    imported: "imported";
+    archived: "archived";
+}>;
+/** Inferred runtime type for {@link SessionStatusSchema}. */
+type SessionStatus = z.infer<typeof SessionStatusSchema>;
+/** Source kind that produced the session. */
+declare const SessionSourceKindSchema: z.ZodEnum<{
+    "claude-code-adapter": "claude-code-adapter";
+    human: "human";
+    import: "import";
+    terminal: "terminal";
+}>;
+/** Inferred runtime type for {@link SessionSourceKindSchema}. */
+type SessionSourceKind = z.infer<typeof SessionSourceKindSchema>;
+/**
+ * Schema for `.basou/sessions/<session_id>/session.yaml`. The minimal
+ * session document carries the actual fields nested under the outer
+ * `session:` key.
+ */
+declare const SessionSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"0.1.0">;
     session: z.ZodObject<{
-        id: z.ZodOptional<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>;
+        id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
         label: z.ZodOptional<z.ZodString>;
         task_id: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
         workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
@@ -924,804 +805,446 @@ declare const SessionImportPayloadSchema: z.ZodObject<{
         working_directory: z.ZodString;
         invocation: z.ZodObject<{
             command: z.ZodString;
-            args: z.ZodArray<z.ZodString>;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
             exit_code: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>;
         related_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        events_log: z.ZodOptional<z.ZodString>;
+        events_log: z.ZodDefault<z.ZodString>;
         summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strict>;
-    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        schema_version: z.ZodLiteral<"0.1.0">;
-        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"session_started">;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"session_ended">;
-        exit_code: z.ZodOptional<z.ZodNumber>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"session_status_changed">;
-        from: z.ZodString;
-        to: z.ZodString;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"approval_requested">;
-        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-        expires_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-        risk_level: z.ZodEnum<{
-            low: "low";
-            medium: "medium";
-            high: "high";
-            critical: "critical";
-        }>;
-        action: z.ZodObject<{
-            kind: z.ZodString;
-        }, z.core.$loose>;
-        reason: z.ZodString;
-        status: z.ZodLiteral<"pending">;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"approval_approved">;
-        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-        resolver: z.ZodOptional<z.ZodString>;
-        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"approval_rejected">;
-        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-        resolver: z.ZodOptional<z.ZodString>;
-        reason: z.ZodString;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"approval_expired">;
-        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"command_executed">;
-        command: z.ZodString;
-        args: z.ZodArray<z.ZodString>;
-        cwd: z.ZodString;
-        exit_code: z.ZodNullable<z.ZodNumber>;
-        signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        received_signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        duration_ms: z.ZodNumber;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"git_snapshot">;
-        head: z.ZodString;
-        branch: z.ZodString;
-        dirty: z.ZodBoolean;
-        staged: z.ZodArray<z.ZodString>;
-        unstaged: z.ZodArray<z.ZodString>;
-        untracked: z.ZodArray<z.ZodString>;
-        ahead: z.ZodOptional<z.ZodNumber>;
-        behind: z.ZodOptional<z.ZodNumber>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"file_changed">;
-        path: z.ZodString;
-        change_type: z.ZodEnum<{
-            added: "added";
-            modified: "modified";
-            deleted: "deleted";
-            renamed: "renamed";
-        }>;
-        old_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"decision_recorded">;
-        decision_id: z.ZodString & z.ZodType<`decision_${string}`, string, z.core.$ZodTypeInternals<`decision_${string}`, string>>;
-        title: z.ZodString;
-        rationale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        alternatives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        rejected_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        linked_events: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>>>;
-        linked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_created">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        title: z.ZodString;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_status_changed">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        from: z.ZodString;
-        to: z.ZodString;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_reconciled">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        removed_created_in_session: z.ZodDefault<z.ZodNullable<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-        created_in_session_replacement: z.ZodDefault<z.ZodNullable<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-        removed_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-    }, z.core.$strict>, z.ZodObject<{
-        schema_version: z.ZodLiteral<"0.1.0">;
-        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_linkage_refreshed">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        added_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-        removed_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
-        final_count: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>, z.ZodObject<{
-        schema_version: z.ZodLiteral<"0.1.0">;
-        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_deleted">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        title: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        schema_version: z.ZodLiteral<"0.1.0">;
-        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"task_archived">;
-        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
-        title: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        schema_version: z.ZodLiteral<"0.1.0">;
-        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"note_added">;
-        body: z.ZodString;
-    }, 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>>;
-        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
-        occurred_at: z.ZodString;
-        source: z.ZodString;
-        type: z.ZodLiteral<"adapter_output">;
-        stream: z.ZodEnum<{
-            stdout: "stdout";
-            stderr: "stderr";
-        }>;
-        summary: z.ZodString;
-        raw_ref: z.ZodString;
-        redacted: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>], "type">>;
-}, z.core.$strict>;
-/** Inferred runtime type for {@link SessionImportPayloadSchema}. */
-type SessionImportPayload = z.infer<typeof SessionImportPayloadSchema>;
-/** Inferred runtime type for {@link SessionInnerImportSchema}. */
-type SessionInnerImportInput = z.infer<typeof SessionInnerImportSchema>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link SessionSchema}. */
+type Session = z.infer<typeof SessionSchema>;
 
 /**
- * Absolute paths to the standard `.basou/` directory layout, derived from a
- * given repository root. The shape mirrors the canonical `.basou/` tree
- * (see `docs/spec/workspace.md`). `root` is the `.basou/` directory itself
- * (i.e. `repositoryRoot/.basou`).
- *
- * `files` exposes the well-known top-level files inside `.basou/`. Each path
- * is computed but not created — they are written by their respective
- * subsystems (e.g. `writeManifest` for `manifest.yaml`).
+ * Threshold above which a still-`running` session with no `session_ended`
+ * event is flagged suspect.
  *
- * All fields are deeply readonly; consumers must not mutate the returned
- * object.
+ * 24h: long enough that an active long-running session will not be flagged,
+ * short enough that an abandoned process is surfaced within a working day.
+ * Tunable via CLI option in a later step (continuation backlog #23).
  */
-type BasouPaths = {
-    readonly root: string;
-    readonly sessions: string;
-    readonly tasks: string;
-    readonly approvals: {
-        readonly pending: string;
-        readonly resolved: string;
-    };
-    readonly locks: string;
-    readonly logs: string;
-    readonly raw: string;
-    readonly tmp: string;
-    readonly files: {
-        readonly manifest: string;
-        readonly status: string;
-        readonly handoff: string;
-        readonly decisions: string;
-    };
+declare const STUCK_THRESHOLD_MS: number;
+type SuspectReason = "events_say_ended_but_yaml_running" | "running_no_end_event";
+type SessionEntry = {
+    sessionId: string;
+    session: Session;
+    suspect: boolean;
+    suspectReason: SuspectReason | null;
 };
 /**
- * Compute absolute paths to the standard `.basou/` directory layout under
- * `repositoryRoot`. Pure: performs no I/O and is safe to call before the
- * directory exists.
+ * Per-session degradation reason emitted by {@link loadSessionEntries.onSkip}.
  *
- * @param repositoryRoot Absolute path to the git repository root (the
- *   parent directory of `.basou/`). Caller is responsible for resolving
- *   `process.cwd()` or running `git rev-parse --show-toplevel` upstream;
- *   this function does not validate that the path exists or is a git
- *   repository.
+ * - `session_yaml_missing` (ENOENT) and `session_yaml_invalid` (parse or schema
+ *   failure) both omit the entry from the result.
+ * - `events_jsonl_unreadable` still pushes the entry with `suspect=false` so
+ *   the session row remains visible to the caller; only the suspect check is
+ *   degraded. Matches the existing CLI behaviour at
+ *   `packages/cli/src/commands/session.ts` (suspect-check stderr warning).
  */
-declare function basouPaths(repositoryRoot: string): BasouPaths;
+type SessionSkipReason = "session_yaml_missing" | "session_yaml_invalid" | "events_jsonl_unreadable";
+type LoadSessionEntriesOptions = {
+    /**
+     * Single `now` shared across every {@link classifySuspect} call so that
+     * sessions classified back-to-back observe the same instant. Avoids
+     * boundary races where a session at age ≈ 24h would flip between calls.
+     */
+    now: Date;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+};
 /**
- * Create the standard `.basou/` directory layout under `repositoryRoot`.
- *
- * Idempotent: a no-op on an already-initialized layout. Returns the resolved
- * {@link BasouPaths} so callers can immediately use them.
+ * List session directory names under `paths.sessions`, ULID ascending.
  *
- * Throws if `repositoryRoot/.basou` (or any required subdirectory) exists
- * but is not a directory, or if filesystem permissions prevent creation.
- * All thrown error messages are pathless; the original native error is
- * attached as `cause` for diagnostics.
+ * - Returns `[]` when the sessions directory does not exist (empty workspace
+ *   or pre-init state).
+ * - Throws `Error("Failed to enumerate sessions", { cause })` on other I/O.
+ * - Only directories are returned (`.gitkeep` and other files are filtered).
  *
- * @param repositoryRoot Absolute path to the git repository root. See
- *   {@link basouPaths} for the contract on this parameter.
+ * Sort order is `Array.prototype.sort()` default (Unicode code-point
+ * compare). ULIDs are Crockford base32 in uppercase, so the natural sort
+ * is also chronological session-start order.
  */
-declare function ensureBasouDirectory(repositoryRoot: string): Promise<BasouPaths>;
-
-/** Which side of `.basou/approvals/` an approval YAML lives on. */
-type ApprovalLocation = "pending" | "resolved";
-/** Result returned by {@link loadApproval}: the parsed approval and where it was found. */
-type LoadedApproval = {
-    approval: Approval;
-    location: ApprovalLocation;
-};
+declare function enumerateSessionDirs(paths: BasouPaths): Promise<string[]>;
 /**
- * Locate and load the approval YAML for `approvalId`. Searches resolved
- * first so that a duplicated YAML (the crash-window scenario where both
- * pending and resolved exist for the same id) returns the resolved-side
- * record — matching the dedupe rule used by `approval list` and
- * `resolveApprovalId`. Returns null if neither directory contains the
- * YAML. Throws with a pathless message on read or schema-validation
- * failure.
+ * Read and validate `<paths.sessions>/<sessionId>/session.yaml`.
+ *
+ * - Re-throws the yaml-store fixed-message `"YAML file not found"` for
+ *   ENOENT so the caller can branch on it.
+ * - Throws `Error("Failed to read session.yaml", { cause })` for parse
+ *   failures and schema violations (cause is either the YAML parser error
+ *   or the zod error).
  */
-declare function loadApproval(paths: BasouPaths, approvalId: string): Promise<LoadedApproval | null>;
+declare function readSessionYaml(paths: BasouPaths, sessionId: string): Promise<Session>;
 /**
- * Enumerate approval IDs by inspecting `<id>.yaml` filenames in pending
- * and resolved. ENOENT on either directory is treated as empty (e.g. a
- * workspace that has no resolved approvals yet). YAML parse and schema
- * validation are NOT performed; callers that need the parsed approval
- * should use {@link loadApproval} per ID.
+ * Classify a `running` session as suspect using one of two rules:
+ *
+ * - Rule A (`events_say_ended_but_yaml_running`): events.jsonl contains a
+ *   `session_ended` event but the session.yaml is still `running`. The
+ *   session ended cleanly in the event log but the YAML write was lost or
+ *   never reached.
+ * - Rule B (`running_no_end_event`): no `session_ended` event and the last
+ *   event is older than {@link STUCK_THRESHOLD_MS}. The process likely
+ *   crashed or was killed.
+ *
+ * Sessions that are not `running` are never suspect.
+ *
+ * I/O failure on events.jsonl is re-thrown unwrapped so the caller can
+ * degrade with a warning instead of treating the session as healthy. The
+ * caller is also responsible for surfacing replay warnings via `onWarning`.
  */
-declare function enumerateApprovals(paths: BasouPaths): Promise<{
-    pending: string[];
-    resolved: string[];
+declare function classifySuspect(paths: BasouPaths, sessionId: string, session: Session, now: Date, onWarning?: (warning: ReplayWarning) => void): Promise<{
+    suspect: boolean;
+    suspectReason: SuspectReason | null;
 }>;
 /**
- * Return true when an approval is in `pending` state and its `expires_at`
- * timestamp has elapsed. Used by `basou approval list` / `show` to surface
- * a `(expired)` label without mutating the YAML file. Approval expiry uses
- * lazy-evaluation semantics; actual `approval_expired` event firing is
- * deferred to a later step.
+ * High-level helper that enumerates session dirs, reads each `session.yaml`,
+ * and classifies suspect for `running` sessions in one pass.
  *
- * `now` is taken as a parameter so a single CLI invocation can share one
- * "now" across every record it inspects (avoids boundary races where two
- * reads of `Date.now()` straddle an expiry instant).
+ * Per-session degradations are surfaced via `options.onSkip`:
+ * - `session_yaml_missing` (ENOENT) and `session_yaml_invalid` (parse or
+ *   schema violation): the entry is omitted from the result.
+ * - `events_jsonl_unreadable`: the entry is still pushed with `suspect=false`
+ *   so callers can render the session row plus a CLI-side warning.
+ *
+ * `options.now` is taken once and threaded into every {@link classifySuspect}
+ * call so age comparisons are consistent across sessions.
  */
-declare function isLazyExpired(approval: Approval, now: Date): boolean;
+declare function loadSessionEntries(paths: BasouPaths, options: LoadSessionEntriesOptions): Promise<SessionEntry[]>;
 
+type DecisionsRendererInput = {
+    paths: BasouPaths;
+    nowIso: string;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+};
+type DecisionsRendererResult = {
+    /** Generated body WITHOUT BASOU:GENERATED markers. */
+    body: string;
+    decisionCount: number;
+};
 /**
- * Read a YAML file as `unknown`. Caller MUST validate via a zod schema.
+ * Render the body of `decisions.md` from `decision_recorded` events across
+ * every healthy session in the workspace.
  *
- * Throws Error with pathless message and the original native error attached
- * as `cause` for I/O failures and YAML parse errors. All fs and parse exits
- * go through fixed messages so absolute paths cannot leak via `error.message`.
- */
-declare function readYamlFile(filePath: string): Promise<unknown>;
-/**
- * Write a value as YAML using {@link atomicReplace} for crash-resistant
- * atomicity. The shared helper handles the tmp-file + rename sequence,
- * `wx` collision guard, and best-effort tmp cleanup on failure. This
- * wrapper adds the YAML serialisation and the pathless error vocabulary.
+ * Session enumeration goes through {@link loadSessionEntries} (the same path
+ * the handoff renderer uses) so that `session.yaml`-broken sessions are
+ * skipped in BOTH outputs and the handoff's `decisionCount` summary stays
+ * consistent with the number of sections rendered here.
+ *
+ * Order: `occurred_at` ascending with `decisionId` (= ULID) as tie-breaker.
+ * Both fields are monotonic, so the result is a stable cross-session
+ * timeline.
+ *
+ * The decision rich fields (rationale / alternatives / rejected_reason /
+ * linked_events / linked_files) are rendered when the event carries them.
+ * `linked_events` and `linked_files` are OPAQUE references: the schema only
+ * validates the SHAPE, not existence — references that cannot be resolved
+ * to a known event id or an existing file on disk are surfaced inline as
+ * `(missing)` so cross-workspace round-trips never reject parse-time.
  */
-declare function writeYamlFile(filePath: string, value: unknown): Promise<void>;
+declare function renderDecisions(input: DecisionsRendererInput): Promise<DecisionsRendererResult>;
+
 /**
- * Atomically create a new YAML file. Like {@link writeYamlFile} but
- * delegates to {@link atomicCreate} so a pre-existing target fails with
- * EEXIST instead of being silently overwritten.
+ * Append a single Basou event to `<sessionDir>/events.jsonl`.
  *
- * Used by `basou approval approve` / `reject` to write the resolved-side
- * YAML, so a concurrent resolver cannot overwrite an already-resolved
- * approval.
+ * The event is validated against the discriminated union {@link EventSchema}
+ * before being serialized as a single JSONL line (UTF-8, terminated by `\n`).
+ * Validation enforces the per-variant contract (required fields, source
+ * vocabulary, strict variants such as `adapter_output`).
  *
- * Throws `Error("Failed to write YAML file", { cause })` on failure; if
- * `cause.code === "EEXIST"` the caller can detect a target-exists race.
+ * Atomicity: writes go through `appendFile` which uses `O_APPEND`. Lines up
+ * to `PIPE_BUF` bytes (Linux 4096 / macOS 512) are written atomically by the
+ * kernel; longer lines may interleave with concurrent writers and are not
+ * recovered here. v0.1 assumes a single writer per session, so partial-line
+ * recovery is delegated to the read side (event replay) when introduced.
+ *
+ * Throws if validation fails or the underlying append errors. The thrown
+ * Error message is pathless; the original error is attached as `cause`.
+ *
+ * @param sessionDir absolute path to `.basou/sessions/<session_id>/`
+ * @param event unknown payload to validate and append
  */
-declare function linkYamlFile(filePath: string, value: unknown): Promise<void>;
+declare function appendEvent(sessionDir: string, event: unknown): Promise<void>;
 /**
- * Overwrite an existing YAML file atomically. Like {@link writeYamlFile}
- * but with a distinct pathless message label, used for files that
- * legitimately need in-place mutation (e.g. session.yaml's status /
- * ended_at lifecycle updates).
+ * Write `events.jsonl` in one atomic tmp+rename pass via {@link atomicReplace},
+ * validating every event against {@link EventSchema} before any disk I/O so
+ * a payload that fails validation never leaves a partial file behind.
+ *
+ * The helper is used by the round-trip importer (`session-import.ts`) and the
+ * ad-hoc session orchestrator (`ad-hoc-session.ts`) where a small, fixed batch
+ * of events must land together or not at all. Zero events produces a
+ * zero-byte file so the session_yaml `events_log` pointer remains valid.
+ *
+ * Throws `"Invalid Basou event payload"` (same fixed message as
+ * {@link appendEvent}) on validation failure, or `"Failed to write
+ * events.jsonl"` on a disk I/O failure. The original native error is attached
+ * as `cause`.
  */
-declare function overwriteYamlFile(filePath: string, value: unknown): Promise<void>;
+declare function writeEventsBulk(sessionDir: string, events: Event[]): Promise<void>;
 
 /**
- * Inputs for {@link createManifest}. Optional fields drop out of the
- * resulting Manifest entirely (they are not emitted as `null`/`undefined`
- * in YAML); pass `null` for `repositoryUrl` to keep an explicit `null`.
- */
-type CreateManifestInput = {
-    workspaceName: string;
-    projectName?: string;
-    projectDescription?: string;
-    repositoryUrl?: string | null;
-    /** Override for tests; defaults to `new Date()`. */
-    now?: Date;
-    /** Override for tests; defaults to a freshly generated `ws_<ULID>`. */
-    workspaceId?: PrefixedId<"ws">;
-};
-/**
- * Build a fresh Manifest object that satisfies the manifest schema's
- * minimum shape. Performs no I/O. Returned object is parse-validated by
- * `ManifestSchema`.
+ * Status classification used by the `file_changed` event schema. Limited to
+ * the four classes that simple-git's `git diff --name-status` reliably
+ * surfaces; copy / unmerged / typechange entries are intentionally dropped
+ * to keep the event payload shape narrow.
  */
-declare function createManifest(input: CreateManifestInput): Manifest;
+type FileChangeStatus = "added" | "modified" | "deleted" | "renamed";
 /**
- * Write a Manifest to `paths.files.manifest`. Re-validates via
- * `ManifestSchema` before serialization.
- *
- * Refuses to overwrite an existing manifest unless `force: true`.
+ * Single file-level change observed between two refs. `old_path` is set
+ * only for `renamed` entries (the previous path of the file).
  */
-declare function writeManifest(paths: BasouPaths, manifest: Manifest, options?: {
-    force?: boolean;
-}): Promise<void>;
+type FileChange = {
+    path: string;
+    old_path?: string;
+    status: FileChangeStatus;
+};
 /**
- * Read and parse a Manifest from `paths.files.manifest`. Throws if the file
- * is missing or contents fail `ManifestSchema` validation.
+ * Result of {@link getDiff}. The `changed_files` array is in git's natural
+ * `--name-status` order; callers requiring deterministic ordering should
+ * sort by `path` themselves.
  */
-declare function readManifest(paths: BasouPaths): Promise<Manifest>;
-
-type AppendBasouGitignoreResult = {
-    /** True if the block was appended (or the file was newly created). */
-    readonly appended: boolean;
+type DiffResult = {
+    changed_files: FileChange[];
 };
 /**
- * Append Basou's default `.gitignore` block to `repositoryRoot/.gitignore`.
+ * Compute the file-level diff between two git refs.
  *
- * The block contents are derived from the Basou v0.1 specification (the
- * standard ignore + commit recommendations). Callers must pass an absolute
- * path to a Git repository root.
+ * Returns a list of changed file paths classified by status (added /
+ * modified / deleted / renamed). Diff content is intentionally NOT
+ * returned — `file_changed` events record paths only, and raw diff bodies
+ * are excluded so the trace cannot inadvertently leak source code that may
+ * be sensitive. Use `git show <ref>` to obtain the underlying diff.
  *
- * 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` is a symlink, the link is followed and the target file
- *   is updated. Symlinks are not rejected.
+ * Pathless contract: every thrown message is a fixed string from the set
+ * {`Not a git repository`, `Git executable not found in PATH. Install git
+ * first.`, `Invalid ref`, `Failed to compute git diff`}; native errors are
+ * preserved on `Error.cause`.
  *
- * On I/O failure throws Error with a pathless message
- * (`Failed to read .gitignore` / `Failed to write .gitignore`) and the
- * original native error attached as `cause`.
+ * Special cases:
+ * - `baseRef === headRef` short-circuits to an empty result
+ * - copy / unmerged / typechange / unknown status codes are skipped
+ *
+ * @param repoRoot absolute path to the git repository root
+ * @param baseRef base ref (e.g. session-start HEAD sha)
+ * @param headRef head ref (e.g. session-end HEAD sha)
  */
-declare function appendBasouGitignore(repositoryRoot: string): Promise<AppendBasouGitignoreResult>;
+declare function getDiff(repoRoot: string, baseRef: string, headRef: string): Promise<DiffResult>;
 
 /**
- * The two lock scopes basou uses. `task` guards the read-modify-write window
- * around a single `task.md`; `session` guards the events.jsonl append plus
- * surrounding `session.yaml` mutation for a single session. Two scopes use
- * different lockfile names so they never collide on disk.
+ * Payload subset of `git_snapshot` event, mechanically derived from the
+ * zod-inferred event type. The wrapping event-shape fields
+ * (schema_version, id, session_id, occurred_at, source, type) are added by
+ * the caller (session lifecycle in later steps) when constructing the
+ * event, so the schema remains the single source of truth.
+ *
+ * `ahead` / `behind` are omitted when there is no remote or no upstream
+ * tracking; the schema declares both as optional non-negative integers.
  */
-type LockScope = "task" | "session";
-type LockHandle = {
-    /**
-     * Release the lock by unlinking the lockfile. Best-effort: any unlink error
-     * is swallowed so a doubled release does not raise, and disk state never
-     * holds a stranded lockfile after the caller's `finally` block.
-     */
-    release: () => Promise<void>;
-};
+type GitSnapshot = Omit<GitSnapshotEvent, "schema_version" | "id" | "session_id" | "occurred_at" | "source" | "type">;
 /**
- * Acquire an advisory lock at `<paths.locks>/<scope>_<id>.lock` for the
- * lifetime of the returned handle. Lockfile body records the holder's pid
- * and acquire timestamp so a competitor can detect stale locks left by a
- * SIGINT'd CLI run and recover automatically.
+ * Resolve the absolute path of the Git repository root that contains `cwd`.
+ * Equivalent to `git rev-parse --show-toplevel`.
  *
- * Acquisition strategy:
- *   1. {@link atomicCreate} the lockfile (POSIX link(2) + EEXIST).
- *   2. On EEXIST, probe the existing lockfile via {@link isStaleLock}.
- *      - If stale (= holder pid is dead or lock is older than
- *        {@link STALE_LOCK_MAX_AGE_MS}), `unlink` the stale file and retry
- *        the atomic create once.
- *      - If still EEXIST after the retry (= another competitor won the race),
- *        throw `"Lock is held by another process"`.
- *      - If the holder is alive, throw `"Lock is held by another process"`
- *        without retrying.
+ * Throws `Error("Git executable not found in PATH. Install git first.")`
+ * with the spawn error attached as `cause` when git itself is missing.
+ * Throws `Error("Not a git repository")` (without command-specific suffix)
+ * when `cwd` is not inside a repository — callers MAY wrap with their own
+ * "Run 'git init' first, then re-run 'basou XXX'." suffix.
  *
- * The caller MUST call `release()` (typically from a `finally` block); the
- * `process.exit()` path or a fatal crash relies on stale-lock detection on
- * the next acquire to recover.
+ * Pathless contract: the thrown message never embeds `cwd` or any absolute
+ * path; native errors are kept on `error.cause` for verbose surfacing.
  */
-declare function acquireLock(paths: BasouPaths, scope: LockScope, resourceId: string): Promise<LockHandle>;
-
+declare function resolveRepositoryRoot(cwd: string): Promise<string>;
 /**
- * Walk the cause chain (up to `depth` levels) looking for an Error whose
- * errno-style `code` matches `code`. Returns true on the first match.
- * Resilient to wrapper depth changes so that ENOENT detection survives
- * future error-wrapping refactors.
+ * Read `remote.origin.url` from the local repository config. Returns
+ * `undefined` if the remote is unset, the value is empty, or the lookup
+ * fails for any reason (best-effort).
+ *
+ * The `--local` scope is critical: callers MUST NOT pick up the developer's
+ * global remote.origin.url, which could leak the wrong repository URL into
+ * `manifest.yaml`.
  */
-declare function findErrorCode(error: unknown, code: string, depth?: number): boolean;
-
+declare function tryRemoteUrl(repositoryRoot: string): Promise<string | undefined>;
 /**
- * Refuse to operate on `.basou` if it is a symlink or not a directory. This
- * prevents `writeStatus` from being tricked into writing `status.json`
- * outside the repository root via a swapped `.basou` symlink. Mirrors
- * `ensureBasouDirectory`'s lstat-based guard.
+ * Build a {@link GitSnapshot} for the repository at `repositoryRoot`. The
+ * caller is responsible for ensuring `repositoryRoot` is the canonical root
+ * (typically obtained via {@link resolveRepositoryRoot}); this function
+ * verifies repo membership via `git rev-parse --is-inside-work-tree` to
+ * distinguish a non-git directory from an empty repository.
  *
- * If `.basou` is absent the underlying ENOENT is propagated (wrapped) so
- * callers can map it to "workspace not initialized" via `findErrorCode`.
+ * Edge cases:
+ * - **non-git directory**: throws `Error("Not a git repository")`
+ * - **empty repo (no commits)**: throws `Error("No commits in repository")`
+ * - **detached HEAD**: `branch = "HEAD"`, `head = commit hash`,
+ *   `ahead`/`behind` omitted
+ * - **no remote / no upstream tracking**: `ahead`/`behind` omitted
  *
- * Note: this is a baseline safety net, not a TOCTOU fix — the directory
- * could still be replaced between this check and the subsequent write. The
- * goal is to detect already-swapped symlinks, not to race-proof the
- * filesystem.
+ * Pathless contract preserved on every throw path.
  */
-declare function assertBasouRootSafe(rootPath: string): Promise<void>;
+declare function getSnapshot(repositoryRoot: string): Promise<GitSnapshot>;
+
 /**
- * Build a StatusSnapshot from a manifest plus the path layout, observing
- * each subdirectory's presence via `lstat`. Read-only with respect to the
- * workspace state; writes nothing. The result is re-validated by
- * `StatusSchema.parse` before being returned.
+ * Allowed ID type prefixes for Basou entities.
  *
- * @param input.now Override for testing; defaults to `new Date()`.
+ * Frozen at runtime so that mutating the exported array cannot diverge from
+ * the validation set used internally. The single source of truth for both
+ * the `IdPrefix` type and runtime prefix checks.
  */
-declare function buildStatusSnapshot(input: {
-    manifest: Manifest;
-    paths: BasouPaths;
-    now?: Date;
-}): Promise<StatusSnapshot>;
-/**
- * Atomically write a StatusSnapshot to `paths.files.status`.
- *
- * Re-validates via `StatusSchema.parse` before any file I/O, so an invalid
- * snapshot throws synchronously and never overwrites the existing
- * `status.json`. Delegates the tmp-file + rename pass to {@link atomicReplace}.
- *
- * **Precondition**: callers MUST invoke {@link assertBasouRootSafe} on
- * `paths.root` first to ensure `.basou` is a real directory and not a
- * swapped symlink. `writeStatus` does not redo this guard — it trusts the
- * caller — so a direct invocation without the guard could write
- * `status.json` outside the repository root.
- */
-declare function writeStatus(paths: BasouPaths, snapshot: StatusSnapshot): Promise<void>;
+declare const ID_PREFIXES: readonly ["ws", "task", "ses", "evt", "appr", "decision"];
 /**
- * Read `.basou/status.json` for the current schema_version (0.1.0). This
- * is a cache reader only; cross-version migration is not supported here.
- * Older or newer status.json shapes will fail `StatusSchema.parse` —
- * callers regenerate by calling `buildStatusSnapshot` + `writeStatus`.
+ * Type prefix used for Basou entity IDs.
+ * Format: `<prefix>_<26-char ULID>`, e.g. `ws_01HXABCDEF1234567890ABCDEF`.
  */
-declare function readStatus(paths: BasouPaths): Promise<StatusSnapshot>;
-
+type IdPrefix = (typeof ID_PREFIXES)[number];
 /**
- * Recoverable warning surfaced via {@link ReplayOptions.onWarning}. The replay
- * generator never throws on these — it skips the offending line and continues.
+ * A Basou entity ID as a template literal type.
  *
- * `partial_trailing_line` indicates the events.jsonl did not end with `\n` and
- * the unterminated tail parsed as a complete event. The line is dropped
- * instead of yielded so consumers cannot accidentally observe a
- * partially-written record.
+ * `PrefixedId<"ses">` narrows to ``ses_${string}`` so a session schema can
+ * preserve the prefix in its inferred type beyond runtime validation.
  */
-type ReplayWarning = {
-    kind: "partial_trailing_line";
-    line: number;
-} | {
-    kind: "malformed_json";
-    line: number;
-    cause: unknown;
-} | {
-    kind: "schema_violation";
-    line: number;
-    cause: unknown;
-};
-type ReplayOptions = {
-    /**
-     * Hook to receive recoverable warnings (partial line / malformed JSON /
-     * schema violation). When omitted, warnings are silently dropped — callers
-     * that want to surface them (e.g. CLI orchestration) MUST provide this hook.
-     */
-    onWarning?: (warning: ReplayWarning) => void;
-};
+type PrefixedId<P extends IdPrefix = IdPrefix> = `${P}_${string}`;
 /**
- * Stream events from `<sessionDir>/events.jsonl` line by line.
+ * Generate a Crockford Base32 ULID.
  *
- * Behavior:
- * - ENOENT or empty file: yields nothing without warning.
- * - I/O error: throws `Error("Failed to read events.jsonl")` with the native
- *   error attached as `cause`. The thrown message never embeds an absolute
- *   path (pathless contract).
- * - Trailing partial line that parses as a valid event: dropped silently when
- *   {@link ReplayOptions.onWarning} is omitted; otherwise reported as
- *   `partial_trailing_line`. A trailing partial line that fails JSON parsing
- *   is reported as `malformed_json` instead.
- * - Malformed JSON / schema violation: skipped, with the corresponding
- *   warning when a hook is provided.
+ * The result is a 26-character, lexicographically time-sortable identifier.
+ * Multiple calls within the same millisecond are strictly increasing for the
+ * lifetime of the current process.
  *
- * Single-writer-per-session is assumed (see `event-writer.ts` JSDoc on
- * {@link appendEvent}). Concurrent writers may interleave lines beyond
- * `PIPE_BUF` and are not recovered here in v0.1.
- */
-declare function replayEvents(sessionDir: string, options?: ReplayOptions): AsyncGenerator<Event, void, void>;
-/**
- * Eager array helper: collect every event from {@link replayEvents} into
- * memory. Convenience for callers that need the full list in one structure
- * (e.g. `basou session show` rendering).
- */
-declare function readAllEvents(sessionDir: string, options?: ReplayOptions): Promise<Event[]>;
-
-/**
- * Threshold above which a still-`running` session with no `session_ended`
- * event is flagged suspect.
+ * NOTE: `seedTime` is forwarded to the underlying monotonic factory and is
+ * NOT a deterministic seed: repeated calls with the same `seedTime` still
+ * return strictly increasing values, because the factory increments its
+ * internal counter on each call.
  *
- * 24h: long enough that an active long-running session will not be flagged,
- * short enough that an abandoned process is surfaced within a working day.
- * Tunable via CLI option in a later step (continuation backlog #23).
+ * @param seedTime Optional millisecond timestamp passed to the monotonic
+ *   factory. Useful for ordered generation in tests; not deterministic.
  */
-declare const STUCK_THRESHOLD_MS: number;
-type SuspectReason = "events_say_ended_but_yaml_running" | "running_no_end_event";
-type SessionEntry = {
-    sessionId: string;
-    session: Session;
-    suspect: boolean;
-    suspectReason: SuspectReason | null;
-};
+declare function ulid(seedTime?: number): string;
 /**
- * Per-session degradation reason emitted by {@link loadSessionEntries.onSkip}.
+ * Generate a prefixed Basou ID, e.g. `ses_01HXABCDEF1234567890ABCDEF`.
  *
- * - `session_yaml_missing` (ENOENT) and `session_yaml_invalid` (parse or schema
- *   failure) both omit the entry from the result.
- * - `events_jsonl_unreadable` still pushes the entry with `suspect=false` so
- *   the session row remains visible to the caller; only the suspect check is
- *   degraded. Matches the existing CLI behaviour at
- *   `packages/cli/src/commands/session.ts` (suspect-check stderr warning).
+ * The return type preserves the prefix as a template literal type so that
+ * downstream zod schemas can narrow an `IdPrefix` parameter through the API.
+ *
+ * Throws if `prefix` is not one of {@link ID_PREFIXES}. The runtime guard
+ * defends against JavaScript callers and casted TypeScript that bypass the
+ * compile-time `IdPrefix` constraint.
  */
-type SessionSkipReason = "session_yaml_missing" | "session_yaml_invalid" | "events_jsonl_unreadable";
-type LoadSessionEntriesOptions = {
-    /**
-     * Single `now` shared across every {@link classifySuspect} call so that
-     * sessions classified back-to-back observe the same instant. Avoids
-     * boundary races where a session at age ≈ 24h would flip between calls.
-     */
-    now: Date;
-    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
-    onSkip?: (sessionId: string, reason: SessionSkipReason) => void;
-};
+declare function prefixedUlid<P extends IdPrefix>(prefix: P): PrefixedId<P>;
 /**
- * List session directory names under `paths.sessions`, ULID ascending.
+ * Check whether the given string is a valid prefixed Basou ID.
  *
- * - Returns `[]` when the sessions directory does not exist (empty workspace
- *   or pre-init state).
- * - Throws `Error("Failed to enumerate sessions", { cause })` on other I/O.
- * - Only directories are returned (`.gitkeep` and other files are filtered).
+ * Returns true only if the string has shape `<prefix>_<ULID>` where prefix is
+ * one of {@link ID_PREFIXES} and the trailing 26 characters form a valid
+ * Crockford Base32 ULID. Validation combines a strict shape regex (to enforce
+ * the 0-7 leading char and the I/L/O/U exclusion) with the npm `ulid`
+ * library's `isValid` for forward compatibility.
  *
- * Sort order is `Array.prototype.sort()` default (Unicode code-point
- * compare). ULIDs are Crockford base32 in uppercase, so the natural sort
- * is also chronological session-start order.
+ * NOTE: This validates the prefix is known. Schemas that require a specific
+ * prefix (e.g. only `ses_*` for a session ID) must add their own narrowing.
  */
-declare function enumerateSessionDirs(paths: BasouPaths): Promise<string[]>;
+declare function isValidPrefixedId(value: string): boolean;
+
 /**
- * Read and validate `<paths.sessions>/<sessionId>/session.yaml`.
- *
- * - Re-throws the yaml-store fixed-message `"YAML file not found"` for
- *   ENOENT so the caller can branch on it.
- * - Throws `Error("Failed to read session.yaml", { cause })` for parse
- *   failures and schema violations (cause is either the YAML parser error
- *   or the zod error).
+ * Schema for `.basou/manifest.yaml`. The minimal manifest carries
+ * schema_version, basou_version, workspace metadata, project info, enabled
+ * capabilities, approval policy, adapter config, and git policy. The
+ * `adapters."claude-code"` key uses a hyphen; downstream code accesses it
+ * via bracket notation.
  */
-declare function readSessionYaml(paths: BasouPaths, sessionId: string): Promise<Session>;
+declare const ManifestSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"0.1.0">;
+    basou_version: z.ZodLiteral<"0.1.0">;
+    workspace: z.ZodObject<{
+        id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+        name: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>;
+    project: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        repository_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    capabilities: z.ZodObject<{
+        enabled: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    approval: z.ZodObject<{
+        required_for: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default_risk_level: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+    }, z.core.$strip>;
+    adapters: z.ZodObject<{
+        "claude-code": z.ZodObject<{
+            enabled: z.ZodBoolean;
+            config_path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    git: z.ZodObject<{
+        events_log: z.ZodDefault<z.ZodEnum<{
+            ignore: "ignore";
+            commit: "commit";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link ManifestSchema}. */
+type Manifest = z.infer<typeof ManifestSchema>;
+
 /**
- * Classify a `running` session as suspect using one of two rules:
+ * Task lifecycle states.
  *
- * - Rule A (`events_say_ended_but_yaml_running`): events.jsonl contains a
- *   `session_ended` event but the session.yaml is still `running`. The
- *   session ended cleanly in the event log but the YAML write was lost or
- *   never reached.
- * - Rule B (`running_no_end_event`): no `session_ended` event and the last
- *   event is older than {@link STUCK_THRESHOLD_MS}. The process likely
- *   crashed or was killed.
+ * The storage layer's `ALLOWED_TRANSITIONS` map (= source of truth in
+ * `tasks.ts`) is the authoritative graph; the comment below is a snapshot.
+ * `planned` reaches `done` / `cancelled` directly so tasks completed (or
+ * abandoned) outside an explicit in-progress phase can close in a single
+ * CLI call:
  *
- * Sessions that are not `running` are never suspect.
+ *   planned → {in_progress | done | cancelled}
+ *   in_progress → {done | cancelled}
+ *   done / cancelled = terminal
  *
- * I/O failure on events.jsonl is re-thrown unwrapped so the caller can
- * degrade with a warning instead of treating the session as healthy. The
- * caller is also responsible for surfacing replay warnings via `onWarning`.
+ * Self-edges are rejected so the audit trail stays monotonic.
  */
-declare function classifySuspect(paths: BasouPaths, sessionId: string, session: Session, now: Date, onWarning?: (warning: ReplayWarning) => void): Promise<{
-    suspect: boolean;
-    suspectReason: SuspectReason | null;
+declare const TaskStatusSchema: z.ZodEnum<{
+    planned: "planned";
+    in_progress: "in_progress";
+    done: "done";
+    cancelled: "cancelled";
 }>;
+/** Inferred runtime type for {@link TaskStatusSchema}. */
+type TaskStatus = z.infer<typeof TaskStatusSchema>;
 /**
- * High-level helper that enumerates session dirs, reads each `session.yaml`,
- * and classifies suspect for `running` sessions in one pass.
- *
- * Per-session degradations are surfaced via `options.onSkip`:
- * - `session_yaml_missing` (ENOENT) and `session_yaml_invalid` (parse or
- *   schema violation): the entry is omitted from the result.
- * - `events_jsonl_unreadable`: the entry is still pushed with `suspect=false`
- *   so callers can render the session row plus a CLI-side warning.
+ * Schema for the YAML front matter of `.basou/tasks/<task_id>.md`.
  *
- * `options.now` is taken once and threaded into every {@link classifySuspect}
- * call so age comparisons are consistent across sessions.
+ * The markdown body after the front matter is intentionally NOT modelled
+ * here — it is free-form user-edited content. The storage layer splits
+ * the file into `task` (this schema) and `body` (the trailing string).
  */
-declare function loadSessionEntries(paths: BasouPaths, options: LoadSessionEntriesOptions): Promise<SessionEntry[]>;
-
-/** Marker line that begins the auto-generated region. */
-declare const GENERATED_START = "<!-- BASOU:GENERATED:START -->";
-/** Marker line that ends the auto-generated region. */
-declare const GENERATED_END = "<!-- BASOU:GENERATED:END -->";
-/**
- * Result of parsing a markdown body for the BASOU:GENERATED marker region.
- *
- * The spec mandates strict line-level matching (see
- * `docs/spec/generated-markdown.md#102-marker-convention`): a marker is
- * only recognized when an entire line is exactly the marker string.
- * Leading/trailing whitespace, comment compression, and BOM are treated as
- * legacy formats (`no_markers`) so that re-generation refuses to silently
- * overwrite a mismatched manual edit.
- */
-type MarkerSection = {
-    kind: "ok";
-    before: string;
-    generated: string;
-    after: string;
-} | {
-    kind: "no_markers";
-} | {
-    kind: "missing_start";
-} | {
-    kind: "missing_end";
-} | {
-    kind: "multiple_pairs";
-} | {
-    kind: "wrong_order";
-};
-/**
- * Read a markdown file as UTF-8 text. Returns `null` when the file does not
- * exist; throws `Error("Failed to read markdown file", { cause })` for other
- * I/O failures (pathless contract — never embed the absolute path in the
- * thrown `message`).
- */
-declare function readMarkdownFile(filePath: string): Promise<string | null>;
-/**
- * Atomically write a markdown body via {@link atomicReplace}. The shared
- * helper handles the tmp-file + rename sequence, `wx` collision guard, and
- * best-effort tmp cleanup on failure.
- *
- * On any failure the original error is re-thrown as
- * `Error("Failed to write markdown file", { cause })` (pathless contract).
- */
-declare function writeMarkdownFile(filePath: string, body: string): Promise<void>;
-/**
- * Parse a markdown body and identify the BASOU:GENERATED marker region.
- *
- * Returns one of six `kind` discriminants:
- * - `ok`: exactly one START line followed by exactly one END line in the
- *   correct order. `before` / `generated` / `after` slice the original
- *   text by character offsets so CRLF / LF are preserved verbatim outside
- *   the marker region.
- * - `no_markers`: both START and END absent (legacy file / fresh write).
- * - `missing_start` / `missing_end`: exactly one of the pair is present.
- * - `multiple_pairs`: more than one START or END line.
- * - `wrong_order`: END appears before START.
- *
- * Matching is strict: leading/trailing whitespace, BOM, and comment
- * compression (`<!--BASOU:...-->`) all bypass the marker and are treated
- * as legacy content.
- */
-declare function parseMarkers(content: string): MarkerSection;
-/**
- * Build the final markdown body by replacing the BASOU:GENERATED region.
- *
- * - `existing === null` (no file yet): return `<START>\n<generated>\n<END>\n`.
- * - existing parses to `ok`: replace the marked region and keep everything
- *   before START and after END untouched (preserving manual additions).
- * - any other parse result: throw a pathless error referencing `fileLabel`.
- *
- * The caller passes `fileLabel` (e.g. `"handoff.md"` or `"decisions.md"`)
- * so the error message is informative without leaking an absolute path.
- */
-declare function renderWithMarkers(existing: string | null, generated: string, fileLabel: string): string;
-
-/**
- * Options for {@link importSessionFromJson}. All fields are optional.
- *
- * - `labelOverride` / `taskIdOverride` come from the CLI `--label` / `--task`
- *   flags and win over the corresponding fields on the input payload.
- * - `dryRun` skips disk writes entirely and returns a preview result.
- */
-type ImportSessionOptions = {
-    labelOverride?: string;
-    taskIdOverride?: string;
-    dryRun?: boolean;
-};
-/**
- * Result of a successful import. `finalStatus` is always the literal
- * `"imported"` (per the import-session lifecycle policy); `finalSourceKind`
- * mirrors the input's `session.source.kind` so round-trip imports preserve
- * provenance.
- *
- * `pathSanitizeReport` summarises how many path-shaped fields the importer
- * rewrote on the way in: `related_files[]` entries plus a single boolean
- * for `working_directory`. The CLI wrapper surfaces this as a one-line
- * stderr warning when the total is non-zero so the operator sees that
- * machine-private prefixes were stripped.
- */
-type ImportSessionResult = {
-    sessionId: PrefixedId<"ses">;
-    eventCount: number;
-    finalStatus: SessionStatus;
-    finalSourceKind: SessionSourceKind;
-    pathSanitizeReport: {
-        relatedFiles: number;
-        workingDirectoryRewritten: boolean;
-    };
-};
-/**
- * Import a round-trip JSON payload into `.basou/sessions/<new>/`. The caller
- * MUST validate the payload against {@link SessionImportPayloadSchema} first
- * and gate the `schema_version === "0.1.0"` literal check externally; this
- * function trusts both invariants.
- *
- * On success a fresh session ID is minted and a complete
- * `session.yaml` + `events.jsonl` pair is written atomically. On any post-
- * mkdir failure the session directory is removed best-effort so partial
- * imports do not leave `session_yaml_missing` half-states behind.
- *
- * Throws `Error` with one of the fixed messages enumerated by the import contract
- * §"Error messages" table; the original native error is attached as `cause`
- * for `--verbose` rendering.
- */
-declare function importSessionFromJson(paths: BasouPaths, manifest: Manifest, payload: SessionImportPayload, options: ImportSessionOptions): Promise<ImportSessionResult>;
+declare const TaskSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"0.1.0">;
+    task: z.ZodObject<{
+        id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        title: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            planned: "planned";
+            in_progress: "in_progress";
+            done: "done";
+            cancelled: "cancelled";
+        }>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+        created_in_session: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link TaskSchema}. */
+type Task = z.infer<typeof TaskSchema>;
 
 /**
  * Thrown when the ad-hoc session was fully written to disk (4 lifecycle
@@ -2381,10 +1904,88 @@ type ArchiveTaskResult = {
  */
 declare function archiveTask(input: ArchiveTaskInput): Promise<ArchiveTaskResult>;
 
+/** Input contract for {@link renderHandoff}. */
+type HandoffRendererInput = {
+    paths: BasouPaths;
+    /** ISO timestamp embedded in the generated body header. Caller-provided for testability. */
+    nowIso: string;
+    /** Forwarded to {@link replayEvents} / {@link loadSessionEntries} per session. */
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    /**
+     * Per-session degradation reasons (missing/invalid session.yaml or
+     * unreadable events.jsonl). The CLI maps `events_jsonl_unreadable` to the
+     * existing suspect-check stderr wording to keep the user-facing surface
+     * consistent with `basou session list`.
+     */
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+    /**
+     * Per-task degradation reasons (invalid front matter / unreadable file).
+     * Surfaced so the CLI can warn the operator about a malformed task.md
+     * without aborting the handoff render.
+     */
+    onTaskSkip?: (taskId: string, reason: TaskSkipReason) => void;
+    /** Maximum related_files entries to display before `... +N more`. Default 20. */
+    relatedFilesLimit?: number;
+};
+type HandoffRendererResult = {
+    /** Generated body WITHOUT BASOU:GENERATED markers (markdown-store wraps them). */
+    body: string;
+    sessionCount: number;
+    decisionCount: number;
+    pendingApprovalsCount: number;
+    suspectCount: number;
+    /** Total number of task.md files successfully loaded. */
+    taskCount: number;
+    /** Tasks whose status is `planned` or `in_progress` (= shown in 次に実行すべき作業). */
+    pendingTaskCount: number;
+};
+/**
+ * Render the body of `handoff.md` from the current workspace state.
+ *
+ * The renderer is a pure function (no I/O beyond {@link replayEvents} /
+ * {@link loadSessionEntries} / {@link enumerateApprovals}). It assembles the
+ * the spec's `handoff.md` sections in order:
+ *
+ * 1. `現在の状態`: latest live session (status not archived, source not import).
+ * 2. `直近の変更ファイル`: union of `related_files` across sessions, dedup +
+ *    sorted asc + truncated to `relatedFilesLimit` (default 20).
+ * 3. `直近の判断`: latest `decision_recorded` event (chronological).
+ * 4. `未決事項`: pending-approval count + suspect-session count.
+ * 5. `次に読むべきファイル`: `.basou/decisions.md` + top-3 related files
+ *    (the same `displayedFiles` source is intentionally reused in two
+ *    sections — overview vs. resume context).
+ * 6. `次に実行すべき作業`: placeholder until task events land.
+ * 7. `セッション一覧`: all sessions newest first with inline suspect labels.
+ *
+ * Session enumeration goes through {@link loadSessionEntries} so the set of
+ * sessions whose `decision_recorded` events we replay matches the
+ * decisions renderer.
+ */
+declare function renderHandoff(input: HandoffRendererInput): Promise<HandoffRendererResult>;
+
+/**
+ * Parse a unit-suffixed duration string (e.g. `30s`, `5m`, `1h`, `100ms`)
+ * into milliseconds.
+ *
+ * Rejects formats that cannot represent a positive, finite millisecond
+ * value: malformed inputs, zero, leading-zero values, and computations that
+ * overflow to `Infinity`. The returned number is always a positive integer.
+ *
+ * Supported units: `ms` (milliseconds), `s` (seconds), `m` (minutes),
+ * `h` (hours).
+ *
+ * @param input duration string with required unit suffix
+ * @returns duration in milliseconds (positive, finite)
+ * @throws Error with message
+ *   `Invalid duration: <input>. Expected format: <positive-integer><unit> where unit is ms/s/m/h`
+ *   for format errors, or `Duration overflow: <input>` for non-finite results.
+ */
+declare function parseDuration(input: string): number;
+
 /**
  * Resolve a possibly-truncated session id prefix to a full session id by
  * scanning `<paths.sessions>/`. Existing message contract (carried over
- * from `packages/cli/src/commands/session.ts` 経由の Step 12 実装) is
+ * from `packages/cli/src/commands/session.ts`) is
  * preserved exactly so callers that grep stderr keep working:
  *
  *   - `"Session id is empty"`
@@ -2492,413 +2093,813 @@ type SanitizeRelatedFilesResult = {
  */
 declare function sanitizeRelatedFiles(paths: ReadonlyArray<string>, opts: SanitizePathOptions): SanitizeRelatedFilesResult;
 
-/** Input contract for {@link renderHandoff}. */
-type HandoffRendererInput = {
-    paths: BasouPaths;
-    /** ISO timestamp embedded in the generated body header. Caller-provided for testability. */
-    nowIso: string;
-    /** Forwarded to {@link replayEvents} / {@link loadSessionEntries} per session. */
-    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
-    /**
-     * Per-session degradation reasons (missing/invalid session.yaml or
-     * unreadable events.jsonl). The CLI maps `events_jsonl_unreadable` to the
-     * existing suspect-check stderr wording to keep the user-facing surface
-     * consistent with `basou session list`.
-     */
-    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
-    /**
-     * Per-task degradation reasons (invalid front matter / unreadable file).
-     * Surfaced so the CLI can warn the operator about a malformed task.md
-     * without aborting the handoff render.
-     */
-    onTaskSkip?: (taskId: string, reason: TaskSkipReason) => void;
-    /** Maximum related_files entries to display before `... +N more`. Default 20. */
-    relatedFilesLimit?: number;
-};
-type HandoffRendererResult = {
-    /** Generated body WITHOUT BASOU:GENERATED markers (markdown-store wraps them). */
-    body: string;
-    sessionCount: number;
-    decisionCount: number;
-    pendingApprovalsCount: number;
-    suspectCount: number;
-    /** Total number of task.md files successfully loaded. */
-    taskCount: number;
-    /** Tasks whose status is `planned` or `in_progress` (= shown in 次に実行すべき作業). */
-    pendingTaskCount: number;
-};
 /**
- * Render the body of `handoff.md` from the current workspace state.
+ * Internal abstraction over child-process execution.
  *
- * The renderer is a pure function (no I/O beyond {@link replayEvents} /
- * {@link loadSessionEntries} / {@link enumerateApprovals}). It assembles the
- * the spec's `handoff.md` sections in order:
+ * 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.
  *
- * 1. `現在の状態`: latest live session (status not archived, source not import).
- * 2. `直近の変更ファイル`: union of `related_files` across sessions, dedup +
- *    sorted asc + truncated to `relatedFilesLimit` (default 20).
- * 3. `直近の判断`: latest `decision_recorded` event (chronological).
- * 4. `未決事項`: pending-approval count + suspect-session count.
- * 5. `次に読むべきファイル`: `.basou/decisions.md` + top-3 related files
- *    (the same `displayedFiles` source is intentionally reused in two
- *    sections — overview vs. resume context).
- * 6. `次に実行すべき作業`: placeholder until task events land.
- * 7. `セッション一覧`: all sessions newest first with inline suspect labels.
+ * 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.
  *
- * Session enumeration goes through {@link loadSessionEntries} so the set of
- * sessions whose `decision_recorded` events we replay matches the
- * decisions renderer.
+ * - `"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.
  */
-declare function renderHandoff(input: HandoffRendererInput): Promise<HandoffRendererResult>;
-
-type DecisionsRendererInput = {
-    paths: BasouPaths;
-    nowIso: string;
-    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
-    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+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 DecisionsRendererResult = {
-    /** Generated body WITHOUT BASOU:GENERATED markers. */
-    body: string;
-    decisionCount: number;
+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>;
 };
+
 /**
- * Render the body of `decisions.md` from `decision_recorded` events across
- * every healthy session in the workspace.
- *
- * Session enumeration goes through {@link loadSessionEntries} (the same path
- * the handoff renderer uses) so that `session.yaml`-broken sessions are
- * skipped in BOTH outputs and the handoff's `decisionCount` summary stays
- * consistent with the number of sections rendered here.
+ * Spawn-based ProcessRunner implementation.
  *
- * Order: `occurred_at` ascending with `decisionId` (= ULID) as tie-breaker.
- * Both fields are monotonic, so the result is a stable cross-session
- * timeline.
+ * 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`.
  *
- * The decision rich fields (rationale / alternatives / rejected_reason /
- * linked_events / linked_files) are rendered when the event carries them.
- * `linked_events` and `linked_files` are OPAQUE references: the schema only
- * validates the SHAPE, not existence — references that cannot be resolved
- * to a known event id or an existing file on disk are surfaced inline as
- * `(missing)` so cross-workspace round-trips never reject parse-time.
+ * 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 function renderDecisions(input: DecisionsRendererInput): Promise<DecisionsRendererResult>;
+declare class ChildProcessRunner implements ProcessRunner {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+}
+
+declare const SessionInnerImportSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>;
+    label: z.ZodOptional<z.ZodString>;
+    task_id: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
+    workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+    source: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "claude-code-adapter": "claude-code-adapter";
+            human: "human";
+            import: "import";
+            terminal: "terminal";
+        }>;
+        version: z.ZodLiteral<"0.1.0">;
+    }, z.core.$strip>;
+    started_at: z.ZodString;
+    ended_at: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        initialized: "initialized";
+        running: "running";
+        waiting_approval: "waiting_approval";
+        completed: "completed";
+        failed: "failed";
+        interrupted: "interrupted";
+        imported: "imported";
+        archived: "archived";
+    }>;
+    working_directory: z.ZodString;
+    invocation: z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+        exit_code: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    related_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    events_log: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Schema for the round-trip JSON payload accepted by `basou session import
+ * --format json`. The top level is `.strict()`; unknown keys at the outer
+ * envelope are rejected.
+ */
+declare const SessionImportPayloadSchema: z.ZodObject<{
+    schema_version: z.ZodString;
+    session: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>;
+        label: z.ZodOptional<z.ZodString>;
+        task_id: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
+        workspace_id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+        source: z.ZodObject<{
+            kind: z.ZodEnum<{
+                "claude-code-adapter": "claude-code-adapter";
+                human: "human";
+                import: "import";
+                terminal: "terminal";
+            }>;
+            version: z.ZodLiteral<"0.1.0">;
+        }, z.core.$strip>;
+        started_at: z.ZodString;
+        ended_at: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            initialized: "initialized";
+            running: "running";
+            waiting_approval: "waiting_approval";
+            completed: "completed";
+            failed: "failed";
+            interrupted: "interrupted";
+            imported: "imported";
+            archived: "archived";
+        }>;
+        working_directory: z.ZodString;
+        invocation: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+            exit_code: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        related_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        events_log: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        schema_version: z.ZodLiteral<"0.1.0">;
+        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"session_started">;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"session_ended">;
+        exit_code: z.ZodOptional<z.ZodNumber>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"session_status_changed">;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"approval_requested">;
+        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+        expires_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        risk_level: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        action: z.ZodObject<{
+            kind: z.ZodString;
+        }, z.core.$loose>;
+        reason: z.ZodString;
+        status: z.ZodLiteral<"pending">;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"approval_approved">;
+        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+        resolver: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"approval_rejected">;
+        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+        resolver: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"approval_expired">;
+        approval_id: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"command_executed">;
+        command: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+        cwd: z.ZodString;
+        exit_code: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        received_signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        duration_ms: z.ZodNumber;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"git_snapshot">;
+        head: z.ZodString;
+        branch: z.ZodString;
+        dirty: z.ZodBoolean;
+        staged: z.ZodArray<z.ZodString>;
+        unstaged: z.ZodArray<z.ZodString>;
+        untracked: z.ZodArray<z.ZodString>;
+        ahead: z.ZodOptional<z.ZodNumber>;
+        behind: z.ZodOptional<z.ZodNumber>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"file_changed">;
+        path: z.ZodString;
+        change_type: z.ZodEnum<{
+            added: "added";
+            modified: "modified";
+            deleted: "deleted";
+            renamed: "renamed";
+        }>;
+        old_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"decision_recorded">;
+        decision_id: z.ZodString & z.ZodType<`decision_${string}`, string, z.core.$ZodTypeInternals<`decision_${string}`, string>>;
+        title: z.ZodString;
+        rationale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        alternatives: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        rejected_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        linked_events: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>>>;
+        linked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_created">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        title: z.ZodString;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_status_changed">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_reconciled">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        removed_created_in_session: z.ZodDefault<z.ZodNullable<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+        created_in_session_replacement: z.ZodDefault<z.ZodNullable<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+        removed_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        schema_version: z.ZodLiteral<"0.1.0">;
+        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_linkage_refreshed">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        added_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+        removed_linked_sessions: z.ZodDefault<z.ZodArray<z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>>>;
+        final_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        schema_version: z.ZodLiteral<"0.1.0">;
+        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_deleted">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        title: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        schema_version: z.ZodLiteral<"0.1.0">;
+        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"task_archived">;
+        task_id: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+        title: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        schema_version: z.ZodLiteral<"0.1.0">;
+        id: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"note_added">;
+        body: z.ZodString;
+    }, 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>>;
+        session_id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        occurred_at: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodLiteral<"adapter_output">;
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        summary: z.ZodString;
+        raw_ref: z.ZodString;
+        redacted: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+/** Inferred runtime type for {@link SessionImportPayloadSchema}. */
+type SessionImportPayload = z.infer<typeof SessionImportPayloadSchema>;
+/** Inferred runtime type for {@link SessionInnerImportSchema}. */
+type SessionInnerImportInput = z.infer<typeof SessionInnerImportSchema>;
+
+/**
+ * Schema version literal pinned to "0.1.0" for Basou v0.1.
+ * Reused across every entity schema so inferred types narrow to the literal.
+ */
+declare const SchemaVersionSchema: z.ZodLiteral<"0.1.0">;
+/**
+ * ISO 8601 timestamp with explicit timezone offset (e.g. `+09:00`).
+ *
+ * The spec samples include offsets, so the default zod `.datetime()` (which
+ * rejects offsets) is insufficient; `{ offset: true }` is required.
+ */
+declare const IsoTimestampSchema: z.ZodString;
+/** Workspace ID schema: validates `ws_<26-char ULID>`. */
+declare const WorkspaceIdSchema: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+/** Task ID schema: validates `task_<26-char ULID>`. */
+declare const TaskIdSchema: z.ZodString & z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+/** Session ID schema: validates `ses_<26-char ULID>`. */
+declare const SessionIdSchema: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+/** Event ID schema: validates `evt_<26-char ULID>`. */
+declare const EventIdSchema: z.ZodString & z.ZodType<`evt_${string}`, string, z.core.$ZodTypeInternals<`evt_${string}`, string>>;
+/** Approval ID schema: validates `appr_<26-char ULID>`. */
+declare const ApprovalIdSchema: z.ZodString & z.ZodType<`appr_${string}`, string, z.core.$ZodTypeInternals<`appr_${string}`, string>>;
+/** Decision ID schema: validates `decision_<26-char ULID>`. */
+declare const DecisionIdSchema: z.ZodString & z.ZodType<`decision_${string}`, string, z.core.$ZodTypeInternals<`decision_${string}`, string>>;
+/**
+ * Risk level vocabulary fixed by the spec. Adapters MUST emit one of these
+ * four values; arbitrary strings are rejected at schema parse time.
+ */
+declare const RiskLevelSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>;
+/** Inferred runtime type for {@link RiskLevelSchema}. */
+type RiskLevel = z.infer<typeof RiskLevelSchema>;
+/**
+ * Source attribution for events (e.g. "claude-code-adapter",
+ * "git-capability", "terminal-recording", "local-cli", "human"). Free-form
+ * non-empty string in v0.1; a stricter enum may be introduced post-v0.1.
+ */
+declare const EventSourceSchema: z.ZodString;
+
+/**
+ * Schema for `.basou/status.json` — a forward-incompat cache of the current
+ * workspace state.
+ *
+ * Each level uses `.strict()` so unknown keys are rejected rather than
+ * silently stripped. A v0.1 reader that encounters a future-shape
+ * `status.json` therefore fails parsing instead of returning a partially
+ * empty snapshot; callers regenerate by calling `buildStatusSnapshot` +
+ * `writeStatus` rather than trying to migrate.
+ */
+declare const StatusSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"0.1.0">;
+    generated_at: z.ZodString;
+    workspace: z.ZodObject<{
+        id: z.ZodString & z.ZodType<`ws_${string}`, string, z.core.$ZodTypeInternals<`ws_${string}`, string>>;
+        name: z.ZodString;
+        basou_version: z.ZodLiteral<"0.1.0">;
+    }, z.core.$strict>;
+    directories_present: z.ZodObject<{
+        sessions: z.ZodBoolean;
+        tasks: z.ZodBoolean;
+        approvals_pending: z.ZodBoolean;
+        approvals_resolved: z.ZodBoolean;
+        logs: z.ZodBoolean;
+        raw: z.ZodBoolean;
+        tmp: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred runtime type for {@link StatusSchema}. */
+type StatusSnapshot = z.infer<typeof StatusSchema>;
 
+type AppendBasouGitignoreResult = {
+    /** True if the block was appended (or the file was newly created). */
+    readonly appended: boolean;
+};
 /**
- * Internal abstraction over child-process execution.
+ * Append Basou's default `.gitignore` block to `repositoryRoot/.gitignore`.
  *
- * 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 block contents are derived from the Basou v0.1 specification (the
+ * standard ignore + commit recommendations). Callers must pass an absolute
+ * path to a Git repository root.
  *
- * 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.
+ * 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` is a symlink, the link is followed and the target file
+ *   is updated. Symlinks are not rejected.
+ *
+ * On I/O failure throws Error with a pathless message
+ * (`Failed to read .gitignore` / `Failed to write .gitignore`) and the
+ * original native error attached as `cause`.
  */
+declare function appendBasouGitignore(repositoryRoot: string): Promise<AppendBasouGitignoreResult>;
+
 /**
- * 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.
+ * The two lock scopes basou uses. `task` guards the read-modify-write window
+ * around a single `task.md`; `session` guards the events.jsonl append plus
+ * surrounding `session.yaml` mutation for a single session. Two scopes use
+ * different lockfile names so they never collide on disk.
  */
-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;
+type LockScope = "task" | "session";
+type LockHandle = {
     /**
-     * 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.
+     * Release the lock by unlinking the lockfile. Best-effort: any unlink error
+     * is swallowed so a doubled release does not raise, and disk state never
+     * holds a stranded lockfile after the caller's `finally` block.
      */
-    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>;
+    release: () => Promise<void>;
 };
-
 /**
- * Spawn-based ProcessRunner implementation.
+ * Acquire an advisory lock at `<paths.locks>/<scope>_<id>.lock` for the
+ * lifetime of the returned handle. Lockfile body records the holder's pid
+ * and acquire timestamp so a competitor can detect stale locks left by a
+ * SIGINT'd CLI run and recover automatically.
  *
- * 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`.
+ * Acquisition strategy:
+ *   1. {@link atomicCreate} the lockfile (POSIX link(2) + EEXIST).
+ *   2. On EEXIST, probe the existing lockfile via {@link isStaleLock}.
+ *      - If stale (= holder pid is dead or lock is older than
+ *        {@link STALE_LOCK_MAX_AGE_MS}), `unlink` the stale file and retry
+ *        the atomic create once.
+ *      - If still EEXIST after the retry (= another competitor won the race),
+ *        throw `"Lock is held by another process"`.
+ *      - If the holder is alive, throw `"Lock is held by another process"`
+ *        without retrying.
  *
- * 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.
+ * The caller MUST call `release()` (typically from a `finally` block); the
+ * `process.exit()` path or a fatal crash relies on stale-lock detection on
+ * the next acquire to recover.
  */
-declare class ChildProcessRunner implements ProcessRunner {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
-}
+declare function acquireLock(paths: BasouPaths, scope: LockScope, resourceId: string): Promise<LockHandle>;
 
 /**
- * Payload subset of `git_snapshot` event, mechanically derived from the
- * zod-inferred event type. The wrapping event-shape fields
- * (schema_version, id, session_id, occurred_at, source, type) are added by
- * the caller (session lifecycle in later steps) when constructing the
- * event, so the schema remains the single source of truth.
+ * Inputs for {@link createManifest}. Optional fields drop out of the
+ * resulting Manifest entirely (they are not emitted as `null`/`undefined`
+ * in YAML); pass `null` for `repositoryUrl` to keep an explicit `null`.
+ */
+type CreateManifestInput = {
+    workspaceName: string;
+    projectName?: string;
+    projectDescription?: string;
+    repositoryUrl?: string | null;
+    /** Override for tests; defaults to `new Date()`. */
+    now?: Date;
+    /** Override for tests; defaults to a freshly generated `ws_<ULID>`. */
+    workspaceId?: PrefixedId<"ws">;
+};
+/**
+ * Build a fresh Manifest object that satisfies the manifest schema's
+ * minimum shape. Performs no I/O. Returned object is parse-validated by
+ * `ManifestSchema`.
+ */
+declare function createManifest(input: CreateManifestInput): Manifest;
+/**
+ * Write a Manifest to `paths.files.manifest`. Re-validates via
+ * `ManifestSchema` before serialization.
  *
- * `ahead` / `behind` are omitted when there is no remote or no upstream
- * tracking; the schema declares both as optional non-negative integers.
+ * Refuses to overwrite an existing manifest unless `force: true`.
  */
-type GitSnapshot = Omit<GitSnapshotEvent, "schema_version" | "id" | "session_id" | "occurred_at" | "source" | "type">;
+declare function writeManifest(paths: BasouPaths, manifest: Manifest, options?: {
+    force?: boolean;
+}): Promise<void>;
 /**
- * Resolve the absolute path of the Git repository root that contains `cwd`.
- * Equivalent to `git rev-parse --show-toplevel`.
+ * Read and parse a Manifest from `paths.files.manifest`. Throws if the file
+ * is missing or contents fail `ManifestSchema` validation.
+ */
+declare function readManifest(paths: BasouPaths): Promise<Manifest>;
+
+/** Marker line that begins the auto-generated region. */
+declare const GENERATED_START = "<!-- BASOU:GENERATED:START -->";
+/** Marker line that ends the auto-generated region. */
+declare const GENERATED_END = "<!-- BASOU:GENERATED:END -->";
+/**
+ * Result of parsing a markdown body for the BASOU:GENERATED marker region.
  *
- * Throws `Error("Git executable not found in PATH. Install git first.")`
- * with the spawn error attached as `cause` when git itself is missing.
- * Throws `Error("Not a git repository")` (without command-specific suffix)
- * when `cwd` is not inside a repository — callers MAY wrap with their own
- * "Run 'git init' first, then re-run 'basou XXX'." suffix.
+ * The spec mandates strict line-level matching (see
+ * `docs/spec/generated-markdown.md#102-marker-convention`): a marker is
+ * only recognized when an entire line is exactly the marker string.
+ * Leading/trailing whitespace, comment compression, and BOM are treated as
+ * legacy formats (`no_markers`) so that re-generation refuses to silently
+ * overwrite a mismatched manual edit.
+ */
+type MarkerSection = {
+    kind: "ok";
+    before: string;
+    generated: string;
+    after: string;
+} | {
+    kind: "no_markers";
+} | {
+    kind: "missing_start";
+} | {
+    kind: "missing_end";
+} | {
+    kind: "multiple_pairs";
+} | {
+    kind: "wrong_order";
+};
+/**
+ * Read a markdown file as UTF-8 text. Returns `null` when the file does not
+ * exist; throws `Error("Failed to read markdown file", { cause })` for other
+ * I/O failures (pathless contract — never embed the absolute path in the
+ * thrown `message`).
+ */
+declare function readMarkdownFile(filePath: string): Promise<string | null>;
+/**
+ * Atomically write a markdown body via {@link atomicReplace}. The shared
+ * helper handles the tmp-file + rename sequence, `wx` collision guard, and
+ * best-effort tmp cleanup on failure.
  *
- * Pathless contract: the thrown message never embeds `cwd` or any absolute
- * path; native errors are kept on `error.cause` for verbose surfacing.
+ * On any failure the original error is re-thrown as
+ * `Error("Failed to write markdown file", { cause })` (pathless contract).
  */
-declare function resolveRepositoryRoot(cwd: string): Promise<string>;
+declare function writeMarkdownFile(filePath: string, body: string): Promise<void>;
 /**
- * Read `remote.origin.url` from the local repository config. Returns
- * `undefined` if the remote is unset, the value is empty, or the lookup
- * fails for any reason (best-effort).
+ * Parse a markdown body and identify the BASOU:GENERATED marker region.
+ *
+ * Returns one of six `kind` discriminants:
+ * - `ok`: exactly one START line followed by exactly one END line in the
+ *   correct order. `before` / `generated` / `after` slice the original
+ *   text by character offsets so CRLF / LF are preserved verbatim outside
+ *   the marker region.
+ * - `no_markers`: both START and END absent (legacy file / fresh write).
+ * - `missing_start` / `missing_end`: exactly one of the pair is present.
+ * - `multiple_pairs`: more than one START or END line.
+ * - `wrong_order`: END appears before START.
  *
- * The `--local` scope is critical: callers MUST NOT pick up the developer's
- * global remote.origin.url, which could leak the wrong repository URL into
- * `manifest.yaml`.
+ * Matching is strict: leading/trailing whitespace, BOM, and comment
+ * compression (`<!--BASOU:...-->`) all bypass the marker and are treated
+ * as legacy content.
  */
-declare function tryRemoteUrl(repositoryRoot: string): Promise<string | undefined>;
+declare function parseMarkers(content: string): MarkerSection;
 /**
- * Build a {@link GitSnapshot} for the repository at `repositoryRoot`. The
- * caller is responsible for ensuring `repositoryRoot` is the canonical root
- * (typically obtained via {@link resolveRepositoryRoot}); this function
- * verifies repo membership via `git rev-parse --is-inside-work-tree` to
- * distinguish a non-git directory from an empty repository.
+ * Build the final markdown body by replacing the BASOU:GENERATED region.
  *
- * Edge cases:
- * - **non-git directory**: throws `Error("Not a git repository")`
- * - **empty repo (no commits)**: throws `Error("No commits in repository")`
- * - **detached HEAD**: `branch = "HEAD"`, `head = commit hash`,
- *   `ahead`/`behind` omitted
- * - **no remote / no upstream tracking**: `ahead`/`behind` omitted
+ * - `existing === null` (no file yet): return `<START>\n<generated>\n<END>\n`.
+ * - existing parses to `ok`: replace the marked region and keep everything
+ *   before START and after END untouched (preserving manual additions).
+ * - any other parse result: throw a pathless error referencing `fileLabel`.
  *
- * Pathless contract preserved on every throw path.
+ * The caller passes `fileLabel` (e.g. `"handoff.md"` or `"decisions.md"`)
+ * so the error message is informative without leaking an absolute path.
  */
-declare function getSnapshot(repositoryRoot: string): Promise<GitSnapshot>;
+declare function renderWithMarkers(existing: string | null, generated: string, fileLabel: string): string;
 
 /**
- * Status classification used by the `file_changed` event schema. Limited to
- * the four classes that simple-git's `git diff --name-status` reliably
- * surfaces; copy / unmerged / typechange entries are intentionally dropped
- * to keep the event payload shape narrow.
- */
-type FileChangeStatus = "added" | "modified" | "deleted" | "renamed";
-/**
- * Single file-level change observed between two refs. `old_path` is set
- * only for `renamed` entries (the previous path of the file).
+ * Options for {@link importSessionFromJson}. All fields are optional.
+ *
+ * - `labelOverride` / `taskIdOverride` come from the CLI `--label` / `--task`
+ *   flags and win over the corresponding fields on the input payload.
+ * - `dryRun` skips disk writes entirely and returns a preview result.
  */
-type FileChange = {
-    path: string;
-    old_path?: string;
-    status: FileChangeStatus;
+type ImportSessionOptions = {
+    labelOverride?: string;
+    taskIdOverride?: string;
+    dryRun?: boolean;
 };
 /**
- * Result of {@link getDiff}. The `changed_files` array is in git's natural
- * `--name-status` order; callers requiring deterministic ordering should
- * sort by `path` themselves.
+ * Result of a successful import. `finalStatus` is always the literal
+ * `"imported"` (per the import-session lifecycle policy); `finalSourceKind`
+ * mirrors the input's `session.source.kind` so round-trip imports preserve
+ * provenance.
+ *
+ * `pathSanitizeReport` summarises how many path-shaped fields the importer
+ * rewrote on the way in: `related_files[]` entries plus a single boolean
+ * for `working_directory`. The CLI wrapper surfaces this as a one-line
+ * stderr warning when the total is non-zero so the operator sees that
+ * machine-private prefixes were stripped.
  */
-type DiffResult = {
-    changed_files: FileChange[];
+type ImportSessionResult = {
+    sessionId: PrefixedId<"ses">;
+    eventCount: number;
+    finalStatus: SessionStatus;
+    finalSourceKind: SessionSourceKind;
+    pathSanitizeReport: {
+        relatedFiles: number;
+        workingDirectoryRewritten: boolean;
+    };
 };
 /**
- * Compute the file-level diff between two git refs.
- *
- * Returns a list of changed file paths classified by status (added /
- * modified / deleted / renamed). Diff content is intentionally NOT
- * returned — `file_changed` events record paths only, and raw diff bodies
- * are excluded so the trace cannot inadvertently leak source code that may
- * be sensitive. Use `git show <ref>` to obtain the underlying diff.
- *
- * Pathless contract: every thrown message is a fixed string from the set
- * {`Not a git repository`, `Git executable not found in PATH. Install git
- * first.`, `Invalid ref`, `Failed to compute git diff`}; native errors are
- * preserved on `Error.cause`.
+ * Import a round-trip JSON payload into `.basou/sessions/<new>/`. The caller
+ * MUST validate the payload against {@link SessionImportPayloadSchema} first
+ * and gate the `schema_version === "0.1.0"` literal check externally; this
+ * function trusts both invariants.
  *
- * Special cases:
- * - `baseRef === headRef` short-circuits to an empty result
- * - copy / unmerged / typechange / unknown status codes are skipped
+ * On success a fresh session ID is minted and a complete
+ * `session.yaml` + `events.jsonl` pair is written atomically. On any post-
+ * mkdir failure the session directory is removed best-effort so partial
+ * imports do not leave `session_yaml_missing` half-states behind.
  *
- * @param repoRoot absolute path to the git repository root
- * @param baseRef base ref (e.g. session-start HEAD sha)
- * @param headRef head ref (e.g. session-end HEAD sha)
+ * Throws `Error` with one of the fixed messages enumerated by the import contract
+ * §"Error messages" table; the original native error is attached as `cause`
+ * for `--verbose` rendering.
  */
-declare function getDiff(repoRoot: string, baseRef: string, headRef: string): Promise<DiffResult>;
+declare function importSessionFromJson(paths: BasouPaths, manifest: Manifest, payload: SessionImportPayload, options: ImportSessionOptions): Promise<ImportSessionResult>;
 
 /**
- * Static metadata identifying the claude-code adapter as the session source.
- * Consumed by the CLI orchestration when populating `session.yaml.source`
- * and event `source` fields. The literal `kind` is part of the wire format
- * defined by the session schema; do not change without coordinated schema
- * migration.
- */
-declare const claudeCodeAdapterMetadata: {
-    readonly kind: "claude-code-adapter";
-    readonly version: "0.1.0";
-};
-/**
- * Lookup predicate used by {@link resolveClaudeCodeCommand} to decide
- * whether a candidate executable is reachable on PATH. Exposed as a
- * parameter so tests can substitute a deterministic mock; production
- * callers should omit it and rely on the default `which`-based lookup.
+ * Walk the cause chain (up to `depth` levels) looking for an Error whose
+ * errno-style `code` matches `code`. Returns true on the first match.
+ * Resilient to wrapper depth changes so that ENOENT detection survives
+ * future error-wrapping refactors.
  */
-type CommandLookup = (command: string) => Promise<boolean>;
+declare function findErrorCode(error: unknown, code: string, depth?: number): boolean;
+
 /**
- * Resolve the Claude Code CLI executable name. Tries `claude-code` first
- * and falls back to `claude`; the first candidate found on PATH wins.
+ * Refuse to operate on `.basou` if it is a symlink or not a directory. This
+ * prevents `writeStatus` from being tricked into writing `status.json`
+ * outside the repository root via a swapped `.basou` symlink. Mirrors
+ * `ensureBasouDirectory`'s lstat-based guard.
  *
- * Throws a fixed-message Error when neither candidate is reachable, so
- * callers can present a single user-facing prompt to install the CLI.
+ * If `.basou` is absent the underlying ENOENT is propagated (wrapped) so
+ * callers can map it to "workspace not initialized" via `findErrorCode`.
  *
- * @throws Error("Claude Code CLI not found in PATH. Install claude-code (or claude) first.")
+ * Note: this is a baseline safety net, not a TOCTOU fix — the directory
+ * could still be replaced between this check and the subsequent write. The
+ * goal is to detect already-swapped symlinks, not to race-proof the
+ * filesystem.
  */
-declare function resolveClaudeCodeCommand(lookup?: CommandLookup): Promise<{
-    command: string;
-}>;
+declare function assertBasouRootSafe(rootPath: string): Promise<void>;
 /**
- * Stub for the future `adapter_output` summary generator.
- *
- * v0.1 Step 11 keeps `capture: "none"` and intentionally does not emit
- * `adapter_output` events, so this hook has no production callers yet.
- * The signature is committed so that Step 12+ can implement raw_ref
- * generation without retrofitting the adapter scaffold.
+ * Build a StatusSnapshot from a manifest plus the path layout, observing
+ * each subdirectory's presence via `lstat`. Read-only with respect to the
+ * workspace state; writes nothing. The result is re-validated by
+ * `StatusSchema.parse` before being returned.
  *
- * @throws Error - always; not implemented in v0.1 Step 11.
+ * @param input.now Override for testing; defaults to `new Date()`.
  */
-declare function summarizeAdapterOutput(_stream: "stdout" | "stderr", _raw: string): string;
-
+declare function buildStatusSnapshot(input: {
+    manifest: Manifest;
+    paths: BasouPaths;
+    now?: Date;
+}): Promise<StatusSnapshot>;
 /**
- * Append a single Basou event to `<sessionDir>/events.jsonl`.
- *
- * The event is validated against the discriminated union {@link EventSchema}
- * before being serialized as a single JSONL line (UTF-8, terminated by `\n`).
- * Validation enforces the per-variant contract (required fields, source
- * vocabulary, strict variants such as `adapter_output`).
- *
- * Atomicity: writes go through `appendFile` which uses `O_APPEND`. Lines up
- * to `PIPE_BUF` bytes (Linux 4096 / macOS 512) are written atomically by the
- * kernel; longer lines may interleave with concurrent writers and are not
- * recovered here. v0.1 assumes a single writer per session, so partial-line
- * recovery is delegated to the read side (event replay) when introduced.
+ * Atomically write a StatusSnapshot to `paths.files.status`.
  *
- * Throws if validation fails or the underlying append errors. The thrown
- * Error message is pathless; the original error is attached as `cause`.
+ * Re-validates via `StatusSchema.parse` before any file I/O, so an invalid
+ * snapshot throws synchronously and never overwrites the existing
+ * `status.json`. Delegates the tmp-file + rename pass to {@link atomicReplace}.
  *
- * @param sessionDir absolute path to `.basou/sessions/<session_id>/`
- * @param event unknown payload to validate and append
+ * **Precondition**: callers MUST invoke {@link assertBasouRootSafe} on
+ * `paths.root` first to ensure `.basou` is a real directory and not a
+ * swapped symlink. `writeStatus` does not redo this guard — it trusts the
+ * caller — so a direct invocation without the guard could write
+ * `status.json` outside the repository root.
  */
-declare function appendEvent(sessionDir: string, event: unknown): Promise<void>;
+declare function writeStatus(paths: BasouPaths, snapshot: StatusSnapshot): Promise<void>;
 /**
- * Write `events.jsonl` in one atomic tmp+rename pass via {@link atomicReplace},
- * validating every event against {@link EventSchema} before any disk I/O so
- * a payload that fails validation never leaves a partial file behind.
- *
- * The helper is used by the round-trip importer (`session-import.ts`) and the
- * ad-hoc session orchestrator (`ad-hoc-session.ts`) where a small, fixed batch
- * of events must land together or not at all. Zero events produces a
- * zero-byte file so the session_yaml `events_log` pointer remains valid.
- *
- * Throws `"Invalid Basou event payload"` (same fixed message as
- * {@link appendEvent}) on validation failure, or `"Failed to write
- * events.jsonl"` on a disk I/O failure. The original native error is attached
- * as `cause`.
+ * Read `.basou/status.json` for the current schema_version (0.1.0). This
+ * is a cache reader only; cross-version migration is not supported here.
+ * Older or newer status.json shapes will fail `StatusSchema.parse` —
+ * callers regenerate by calling `buildStatusSnapshot` + `writeStatus`.
  */
-declare function writeEventsBulk(sessionDir: string, events: Event[]): Promise<void>;
+declare function readStatus(paths: BasouPaths): Promise<StatusSnapshot>;
 
 /**
- * Parse a unit-suffixed duration string (e.g. `30s`, `5m`, `1h`, `100ms`)
- * into milliseconds.
+ * Read a YAML file as `unknown`. Caller MUST validate via a zod schema.
  *
- * Rejects formats that cannot represent a positive, finite millisecond
- * value: malformed inputs, zero, leading-zero values, and computations that
- * overflow to `Infinity`. The returned number is always a positive integer.
+ * Throws Error with pathless message and the original native error attached
+ * as `cause` for I/O failures and YAML parse errors. All fs and parse exits
+ * go through fixed messages so absolute paths cannot leak via `error.message`.
+ */
+declare function readYamlFile(filePath: string): Promise<unknown>;
+/**
+ * Write a value as YAML using {@link atomicReplace} for crash-resistant
+ * atomicity. The shared helper handles the tmp-file + rename sequence,
+ * `wx` collision guard, and best-effort tmp cleanup on failure. This
+ * wrapper adds the YAML serialisation and the pathless error vocabulary.
+ */
+declare function writeYamlFile(filePath: string, value: unknown): Promise<void>;
+/**
+ * Atomically create a new YAML file. Like {@link writeYamlFile} but
+ * delegates to {@link atomicCreate} so a pre-existing target fails with
+ * EEXIST instead of being silently overwritten.
  *
- * Supported units: `ms` (milliseconds), `s` (seconds), `m` (minutes),
- * `h` (hours).
+ * Used by `basou approval approve` / `reject` to write the resolved-side
+ * YAML, so a concurrent resolver cannot overwrite an already-resolved
+ * approval.
  *
- * @param input duration string with required unit suffix
- * @returns duration in milliseconds (positive, finite)
- * @throws Error with message
- *   `Invalid duration: <input>. Expected format: <positive-integer><unit> where unit is ms/s/m/h`
- *   for format errors, or `Duration overflow: <input>` for non-finite results.
+ * Throws `Error("Failed to write YAML file", { cause })` on failure; if
+ * `cause.code === "EEXIST"` the caller can detect a target-exists race.
  */
-declare function parseDuration(input: string): number;
+declare function linkYamlFile(filePath: string, value: unknown): Promise<void>;
+/**
+ * Overwrite an existing YAML file atomically. Like {@link writeYamlFile}
+ * but with a distinct pathless message label, used for files that
+ * legitimately need in-place mutation (e.g. session.yaml's status /
+ * ended_at lifecycle updates).
+ */
+declare function overwriteYamlFile(filePath: string, value: unknown): Promise<void>;
 
 /**
  * Version of the `@basou/core` package, aligned with `manifest.yaml`'s