@basou/core 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -2,108 +2,47 @@ 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.
- */
-declare const ID_PREFIXES: readonly ["ws", "task", "ses", "evt", "appr", "decision"];
-/**
- * Type prefix used for Basou entity IDs.
- * Format: `<prefix>_<26-char ULID>`, e.g. `ws_01HXABCDEF1234567890ABCDEF`.
- */
-type IdPrefix = (typeof ID_PREFIXES)[number];
-/**
- * A Basou entity ID as a template literal type.
- *
- * `PrefixedId<"ses">` narrows to ``ses_${string}`` so a session schema can
- * preserve the prefix in its inferred type beyond runtime validation.
+ * 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.
  */
-type PrefixedId<P extends IdPrefix = IdPrefix> = `${P}_${string}`;
+declare const claudeCodeAdapterMetadata: {
+    readonly kind: "claude-code-adapter";
+    readonly version: "0.1.0";
+};
 /**
- * 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.
- *
- * 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.
- *
- * @param seedTime Optional millisecond timestamp passed to the monotonic
- *   factory. Useful for ordered generation in tests; not deterministic.
+ * 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.
  */
-declare function ulid(seedTime?: number): string;
+type CommandLookup = (command: string) => Promise<boolean>;
 /**
- * Generate a prefixed Basou ID, e.g. `ses_01HXABCDEF1234567890ABCDEF`.
+ * Resolve the Claude Code CLI executable name. Tries `claude-code` first
+ * and falls back to `claude`; the first candidate found on PATH wins.
  *
- * 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 a fixed-message Error when neither candidate is reachable, so
+ * callers can present a single user-facing prompt to install the CLI.
  *
- * 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.
+ * @throws Error("Claude Code CLI not found in PATH. Install claude-code (or claude) first.")
  */
-declare function prefixedUlid<P extends IdPrefix>(prefix: P): PrefixedId<P>;
+declare function resolveClaudeCodeCommand(lookup?: CommandLookup): Promise<{
+    command: string;
+}>;
 /**
- * Check whether the given string is a valid prefixed Basou ID.
- *
- * 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.
+ * Stub for the future `adapter_output` summary generator.
  *
- * 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 isValidPrefixedId(value: string): boolean;
-
-/**
- * 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 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.
  *
- * 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.
+ * @throws Error - always; not implemented in this release.
  */
-declare const EventSourceSchema: z.ZodString;
+declare function summarizeAdapterOutput(_stream: "stdout" | "stderr", _raw: string): string;
 
 /**
  * Schema for `.basou/manifest.yaml`. The minimal manifest carries
@@ -154,79 +93,81 @@ declare const ManifestSchema: z.ZodObject<{
 /** 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>;
+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";
+            "claude-code-import": "claude-code-import";
+            "codex-import": "codex-import";
+            human: "human";
+            import: "import";
+            terminal: "terminal";
+        }>;
+        version: z.ZodLiteral<"0.1.0">;
+        external_id: z.ZodOptional<z.ZodString>;
+    }, 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>>;
+    metrics: z.ZodOptional<z.ZodObject<{
+        output_tokens: z.ZodOptional<z.ZodNumber>;
+        input_tokens: z.ZodOptional<z.ZodNumber>;
+        cached_input_tokens: z.ZodOptional<z.ZodNumber>;
+        reasoning_output_tokens: z.ZodOptional<z.ZodNumber>;
+        active_time_ms: z.ZodOptional<z.ZodNumber>;
+        active_intervals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strip>>>;
+        active_gap_cap_ms: z.ZodOptional<z.ZodNumber>;
+        active_time_method: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, 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.
+ * 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 SessionSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"0.1.0">;
+declare const SessionImportPayloadSchema: z.ZodObject<{
+    schema_version: z.ZodString;
     session: z.ZodObject<{
-        id: z.ZodString & z.ZodType<`ses_${string}`, string, z.core.$ZodTypeInternals<`ses_${string}`, string>>;
+        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";
+                "claude-code-import": "claude-code-import";
+                "codex-import": "codex-import";
                 human: "human";
                 import: "import";
                 terminal: "terminal";
             }>;
             version: z.ZodLiteral<"0.1.0">;
+            external_id: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
         started_at: z.ZodString;
         ended_at: z.ZodOptional<z.ZodString>;
@@ -243,94 +184,380 @@ declare const SessionSchema: z.ZodObject<{
         working_directory: z.ZodString;
         invocation: z.ZodObject<{
             command: z.ZodString;
-            args: z.ZodDefault<z.ZodArray<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.ZodDefault<z.ZodString>;
+        events_log: z.ZodOptional<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>>;
+        metrics: z.ZodOptional<z.ZodObject<{
+            output_tokens: z.ZodOptional<z.ZodNumber>;
+            input_tokens: z.ZodOptional<z.ZodNumber>;
+            cached_input_tokens: z.ZodOptional<z.ZodNumber>;
+            reasoning_output_tokens: z.ZodOptional<z.ZodNumber>;
+            active_time_ms: z.ZodOptional<z.ZodNumber>;
+            active_intervals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                start: z.ZodString;
+                end: z.ZodString;
+            }, z.core.$strip>>>;
+            active_gap_cap_ms: z.ZodOptional<z.ZodNumber>;
+            active_time_method: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, 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;
-        label: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            planned: "planned";
-            in_progress: "in_progress";
-            done: "done";
-            cancelled: "cancelled";
+        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";
         }>;
-        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>;
+        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>;
 
 /**
- * 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.
+ * The `source` string stamped on every event derived from a Claude Code
+ * native transcript, and the matching session `source.kind`.
  */
-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>;
+declare const CLAUDE_IMPORT_SOURCE = "claude-code-import";
 /**
- * Schema for `.basou/approvals/{pending,resolved}/<approval_id>.yaml`.
+ * One parsed line of a Claude Code native transcript
+ * (`~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`). The shape is the
+ * vendor's internal message log, not Basou's event schema, so every field
+ * is read defensively — unknown record types and missing fields are skipped
+ * rather than rejected (transcripts are an undocumented format that may gain
+ * fields between Claude Code releases).
+ */
+type ClaudeTranscriptRecord = Record<string, unknown>;
+/** Options for {@link claudeTranscriptToImportPayload}. */
+type ClaudeTranscriptToPayloadOptions = {
+    /** Workspace id of the target Basou workspace (from its manifest). */
+    workspaceId: Manifest["workspace"]["id"];
+    /**
+     * Claude Code session id (transcript filename / `sessionId`). Stored as
+     * `session.source.external_id` so re-imports can be deduplicated. Falls
+     * back to the `sessionId` read from the records when omitted.
+     */
+    externalId?: string;
+};
+/**
+ * Transform a Claude Code native transcript into a Basou
+ * {@link SessionImportPayload}, ready to hand to `importSessionFromJson`.
  *
- * 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`.
+ * This is a pure function: no disk or environment access. It DERIVES Basou's
+ * provenance-level events from the transcript's message-level records, rather
+ * than mapping one-to-one:
  *
- * The `action` field is `{ kind: string }` with `passthrough()` so that
- * adapter-defined keys (e.g. `command`, `path`, `target_url`) survive the
+ * - `session_started` / `session_ended` from the first / last timestamped record.
+ * - `command_executed` from each `Bash` tool use, recorded as `bash -c "<cmd>"`
+ *   (the transcript carries the shell line, not a parsed argv).
+ * - `file_changed` from each `Edit` / `Write` / `NotebookEdit` tool use.
+ * - `decision_recorded` from each `AskUserQuestion` tool use: one decision per
+ *   question, titled `<question> -> <chosen answer>`. The chosen answer is read
+ *   from the paired result record's structured `toolUseResult.answers` map; a
+ *   question with no recorded string answer is skipped.
+ *
+ * Exit codes and per-command durations are not present in the transcript, so
+ * `command_executed.exit_code` is `null` and `duration_ms` is `0`.
+ *
+ * Returns `null` when the transcript has no timestamped records, or no
+ * observable command / file / decision action — such sessions carry no
+ * provenance worth importing and are skipped by the caller.
+ *
+ * Event `id` / `session_id` are placeholders; `importSessionFromJson` mints
+ * fresh ids on the way in. They are valid-by-construction so the payload
+ * still passes `SessionImportPayloadSchema` validation upstream.
+ */
+declare function claudeTranscriptToImportPayload(records: ReadonlyArray<ClaudeTranscriptRecord>, options: ClaudeTranscriptToPayloadOptions): SessionImportPayload | null;
+
+/**
+ * The `source` string stamped on every event derived from an OpenAI Codex
+ * native rollout log, and the matching session `source.kind`.
+ */
+declare const CODEX_IMPORT_SOURCE = "codex-import";
+/**
+ * One parsed line of a Codex rollout log
+ * (`~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl`). Each line is an
+ * envelope `{ type, timestamp, payload }` where `payload` shape depends on
+ * `type`. As with the Claude importer the format is the vendor's internal
+ * log, not Basou's schema, so every field is read defensively — unknown
+ * record / payload types and missing fields are skipped rather than rejected.
+ */
+type CodexRolloutRecord = Record<string, unknown>;
+/** Options for {@link codexRolloutToImportPayload}. */
+type CodexRolloutToPayloadOptions = {
+    /** Workspace id of the target Basou workspace (from its manifest). */
+    workspaceId: Manifest["workspace"]["id"];
+    /**
+     * Codex session id (`session_meta.payload.id`). Stored as
+     * `session.source.external_id` so re-imports can be deduplicated. Falls back
+     * to the id read from the rollout's `session_meta` record when omitted.
+     */
+    externalId?: string;
+};
+/**
+ * Transform a Codex native rollout log into a Basou {@link SessionImportPayload},
+ * ready to hand to `importSessionFromJson`.
+ *
+ * This is a pure function: no disk or environment access. It DERIVES Basou's
+ * provenance-level events from the rollout's message-level records:
+ *
+ * - `session_started` / `session_ended` from the first / last timestamped record.
+ * - `command_executed` from each `exec_command` function call, recorded as
+ *   `bash -c "<cmd>"`. The shell line and working directory come from the
+ *   call's JSON `arguments` (`{ cmd, workdir }`); the exit code and duration
+ *   are parsed from the paired `function_call_output` (matched by `call_id`),
+ *   whose text carries `Process exited with code N` and `Wall time: X seconds`.
+ *
+ * Unlike the Claude importer this derives no `file_changed`: Codex has no
+ * dedicated edit tool and applies edits inside `exec_command` (e.g.
+ * `apply_patch`), so there is no clean file-change signal to map. Decisions
+ * and approvals are likewise not derivable — Codex records an `approval_policy`
+ * (a policy, not a per-action approval) and has no structured question/answer
+ * record. Both are deferred.
+ *
+ * Returns `null` when the rollout has no timestamped records or no observable
+ * `exec_command` — such sessions carry no provenance worth importing and are
+ * skipped by the caller.
+ *
+ * Event `id` / `session_id` are placeholders; `importSessionFromJson` mints
+ * fresh ids on the way in. They are valid-by-construction so the payload still
+ * passes `SessionImportPayloadSchema` validation upstream.
+ */
+declare function codexRolloutToImportPayload(records: ReadonlyArray<CodexRolloutRecord>, options: CodexRolloutToPayloadOptions): SessionImportPayload | null;
+
+/**
+ * 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.
  */
@@ -364,6 +591,107 @@ declare const ApprovalSchema: z.ZodObject<{
 /** Inferred runtime type for {@link ApprovalSchema}. */
 type Approval = z.infer<typeof ApprovalSchema>;
 
+/**
+ * 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`).
+ *
+ * All fields are deeply readonly; consumers must not mutate the returned
+ * object.
+ */
+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;
+    };
+};
+/**
+ * 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 function basouPaths(repositoryRoot: string): BasouPaths;
+/**
+ * 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.
+ *
+ * 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 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;
+};
+/**
+ * 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 function loadApproval(paths: BasouPaths, approvalId: string): Promise<LoadedApproval | null>;
+/**
+ * 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 function enumerateApprovals(paths: BasouPaths): Promise<{
+    pending: string[];
+    resolved: string[];
+}>;
+/**
+ * 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 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>>;
@@ -846,602 +1174,11 @@ type TaskLinkageRefreshedEvent = z.infer<typeof TaskLinkageRefreshedEventSchema>
 /** Narrowed runtime type for the `task_deleted` event variant (.strict()). */
 type TaskDeletedEvent = z.infer<typeof TaskDeletedEventSchema>;
 /** Narrowed runtime type for the `task_archived` event variant (.strict()). */
-type TaskArchivedEvent = z.infer<typeof TaskArchivedEventSchema>;
-/** Narrowed runtime type for the `note_added` event variant. */
-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.
- */
-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>;
-
-/**
- * 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`).
- *
- * All fields are deeply readonly; consumers must not mutate the returned
- * object.
- */
-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;
-    };
-};
-/**
- * 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 function basouPaths(repositoryRoot: string): BasouPaths;
-/**
- * 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.
- *
- * 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 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;
-};
-/**
- * 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 function loadApproval(paths: BasouPaths, approvalId: string): Promise<LoadedApproval | null>;
-/**
- * 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 function enumerateApprovals(paths: BasouPaths): Promise<{
-    pending: string[];
-    resolved: string[];
-}>;
-/**
- * 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 function isLazyExpired(approval: Approval, now: Date): boolean;
-
-/**
- * Read a YAML file as `unknown`. Caller MUST validate via a zod schema.
- *
- * 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.
- *
- * Used by `basou approval approve` / `reject` to write the resolved-side
- * YAML, so a concurrent resolver cannot overwrite an already-resolved
- * approval.
- *
- * Throws `Error("Failed to write YAML file", { cause })` on failure; if
- * `cause.code === "EEXIST"` the caller can detect a target-exists race.
- */
-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>;
-
-/**
- * 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.
- *
- * Refuses to overwrite an existing manifest unless `force: true`.
- */
-declare function writeManifest(paths: BasouPaths, manifest: Manifest, options?: {
-    force?: boolean;
-}): Promise<void>;
-/**
- * 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>;
-
-type AppendBasouGitignoreResult = {
-    /** True if the block was appended (or the file was newly created). */
-    readonly appended: boolean;
-};
-/**
- * Append Basou's default `.gitignore` block to `repositoryRoot/.gitignore`.
- *
- * 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.
- *
- * 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>;
-
-/**
- * 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 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>;
-};
-/**
- * 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.
- *
- * 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.
- *
- * 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 function acquireLock(paths: BasouPaths, scope: LockScope, resourceId: string): Promise<LockHandle>;
-
-/**
- * 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.
- */
-declare function findErrorCode(error: unknown, code: string, depth?: number): boolean;
-
-/**
- * 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.
- *
- * If `.basou` is absent the underlying ENOENT is propagated (wrapped) so
- * callers can map it to "workspace not initialized" via `findErrorCode`.
- *
- * 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 assertBasouRootSafe(rootPath: string): Promise<void>;
-/**
- * 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.
- *
- * @param input.now Override for testing; defaults to `new Date()`.
- */
-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>;
-/**
- * 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 readStatus(paths: BasouPaths): Promise<StatusSnapshot>;
+type TaskArchivedEvent = z.infer<typeof TaskArchivedEventSchema>;
+/** Narrowed runtime type for the `note_added` event variant. */
+type NoteAddedEvent = z.infer<typeof NoteAddedEventSchema>;
+/** Narrowed runtime type for the `adapter_output` event variant (.strict()). */
+type AdapterOutputEvent = z.infer<typeof AdapterOutputEventSchema>;
 
 /**
  * Recoverable warning surfaced via {@link ReplayOptions.onWarning}. The replay
@@ -1499,6 +1236,137 @@ declare function replayEvents(sessionDir: string, options?: ReplayOptions): Asyn
  */
 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.
+ *
+ * - `claude-code-adapter` — a live `basou run claude-code` process wrap.
+ * - `claude-code-import` — derived after the fact from a Claude Code native
+ *   transcript (`~/.claude/projects/*.jsonl`) by `basou import claude-code`.
+ * - `codex-import` — derived after the fact from an OpenAI Codex native
+ *   rollout log (date-partitioned `~/.codex/sessions`) by `basou import codex`.
+ * - `import` — a round-trip of a Basou-format export (`basou session import`).
+ * - `human` / `terminal` — manually-authored / terminal-recorded sessions.
+ */
+declare const SessionSourceKindSchema: z.ZodEnum<{
+    "claude-code-adapter": "claude-code-adapter";
+    "claude-code-import": "claude-code-import";
+    "codex-import": "codex-import";
+    human: "human";
+    import: "import";
+    terminal: "terminal";
+}>;
+/** Inferred runtime type for {@link SessionSourceKindSchema}. */
+type SessionSourceKind = z.infer<typeof SessionSourceKindSchema>;
+/**
+ * Optional per-session metrics, computed at import time from the source tool's
+ * native log. Two groups, both optional because not every source records them:
+ *
+ * - Model-usage rollup (`*_tokens`): the transcript carries per-message token
+ *   usage; these are the session totals. `reasoning_output_tokens` is
+ *   Codex-only, and live `run`/`exec` sessions carry no token usage at all.
+ * - Engaged-time metrics (`active_*`): the billing-oriented active time derived
+ *   from the session's genuine engagement timestamps (conversation turns plus
+ *   action events), with idle gaps capped. `active_intervals` are the merged
+ *   wall-clock ranges (so cross-session totals can de-duplicate overlapping
+ *   work by interval union); `active_time_ms` is their summed duration;
+ *   `active_gap_cap_ms` and `active_time_method` lock the methodology so the
+ *   stored numbers stay interpretable if the method changes later.
+ *
+ * Absent on sessions imported before a given field existed (re-import to
+ * backfill). Live sessions carry no engaged-time metrics and fall back to
+ * event-derived active time at stats time.
+ */
+declare const SessionMetricsSchema: z.ZodObject<{
+    output_tokens: z.ZodOptional<z.ZodNumber>;
+    input_tokens: z.ZodOptional<z.ZodNumber>;
+    cached_input_tokens: z.ZodOptional<z.ZodNumber>;
+    reasoning_output_tokens: z.ZodOptional<z.ZodNumber>;
+    active_time_ms: z.ZodOptional<z.ZodNumber>;
+    active_intervals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strip>>>;
+    active_gap_cap_ms: z.ZodOptional<z.ZodNumber>;
+    active_time_method: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link SessionMetricsSchema}. */
+type SessionMetrics = z.infer<typeof SessionMetricsSchema>;
+/**
+ * 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";
+                "claude-code-import": "claude-code-import";
+                "codex-import": "codex-import";
+                human: "human";
+                import: "import";
+                terminal: "terminal";
+            }>;
+            version: z.ZodLiteral<"0.1.0">;
+            external_id: z.ZodOptional<z.ZodString>;
+        }, 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>>;
+        metrics: z.ZodOptional<z.ZodObject<{
+            output_tokens: z.ZodOptional<z.ZodNumber>;
+            input_tokens: z.ZodOptional<z.ZodNumber>;
+            cached_input_tokens: z.ZodOptional<z.ZodNumber>;
+            reasoning_output_tokens: z.ZodOptional<z.ZodNumber>;
+            active_time_ms: z.ZodOptional<z.ZodNumber>;
+            active_intervals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                start: z.ZodString;
+                end: z.ZodString;
+            }, z.core.$strip>>>;
+            active_gap_cap_ms: z.ZodOptional<z.ZodNumber>;
+            active_time_method: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Inferred runtime type for {@link SessionSchema}. */
+type Session = z.infer<typeof SessionSchema>;
+
 /**
  * Threshold above which a still-`running` session with no `session_ended`
  * event is flagged suspect.
@@ -1595,133 +1463,290 @@ declare function classifySuspect(paths: BasouPaths, sessionId: string, session:
  */
 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 -->";
+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;
+};
 /**
- * Result of parsing a markdown body for the BASOU:GENERATED marker region.
+ * 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.
+ *
+ * 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 renderDecisions(input: DecisionsRendererInput): Promise<DecisionsRendererResult>;
+
+/**
+ * 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.
+ *
+ * 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 appendEvent(sessionDir: string, event: unknown): 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`.
+ */
+declare function writeEventsBulk(sessionDir: string, events: Event[]): Promise<void>;
+
+/**
+ * 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).
+ */
+type FileChange = {
+    path: string;
+    old_path?: string;
+    status: FileChangeStatus;
+};
+/**
+ * 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.
+ */
+type DiffResult = {
+    changed_files: FileChange[];
+};
+/**
+ * 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`.
+ *
+ * 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 getDiff(repoRoot: string, baseRef: string, headRef: string): Promise<DiffResult>;
+
+/**
+ * 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 GitSnapshot = Omit<GitSnapshotEvent, "schema_version" | "id" | "session_id" | "occurred_at" | "source" | "type">;
+/**
+ * Resolve the absolute path of the Git repository root that contains `cwd`.
+ * Equivalent to `git rev-parse --show-toplevel`.
+ *
+ * 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.
+ *
+ * Pathless contract: the thrown message never embeds `cwd` or any absolute
+ * path; native errors are kept on `error.cause` for verbose surfacing.
+ */
+declare function resolveRepositoryRoot(cwd: string): Promise<string>;
+/**
+ * Read `remote.origin.url` from the local repository config. Returns
+ * `undefined` if the remote is unset, the value is empty, or the lookup
+ * 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 tryRemoteUrl(repositoryRoot: string): Promise<string | undefined>;
+/**
+ * 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.
+ *
+ * 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
+ *
+ * Pathless contract preserved on every throw path.
+ */
+declare function getSnapshot(repositoryRoot: string): Promise<GitSnapshot>;
+
+/**
+ * Allowed ID type prefixes for Basou entities.
  *
- * 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.
+ * 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.
  */
-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";
-};
+declare const ID_PREFIXES: readonly ["ws", "task", "ses", "evt", "appr", "decision"];
 /**
- * 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`).
+ * Type prefix used for Basou entity IDs.
+ * Format: `<prefix>_<26-char ULID>`, e.g. `ws_01HXABCDEF1234567890ABCDEF`.
  */
-declare function readMarkdownFile(filePath: string): Promise<string | null>;
+type IdPrefix = (typeof ID_PREFIXES)[number];
 /**
- * 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.
+ * A Basou entity ID as a template literal type.
  *
- * On any failure the original error is re-thrown as
- * `Error("Failed to write markdown file", { cause })` (pathless contract).
+ * `PrefixedId<"ses">` narrows to ``ses_${string}`` so a session schema can
+ * preserve the prefix in its inferred type beyond runtime validation.
  */
-declare function writeMarkdownFile(filePath: string, body: string): Promise<void>;
+type PrefixedId<P extends IdPrefix = IdPrefix> = `${P}_${string}`;
 /**
- * Parse a markdown body and identify the BASOU:GENERATED marker region.
+ * Generate a Crockford Base32 ULID.
  *
- * 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 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.
  *
- * Matching is strict: leading/trailing whitespace, BOM, and comment
- * compression (`<!--BASOU:...-->`) all bypass the marker and are treated
- * as legacy content.
+ * 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.
+ *
+ * @param seedTime Optional millisecond timestamp passed to the monotonic
+ *   factory. Useful for ordered generation in tests; not deterministic.
  */
-declare function parseMarkers(content: string): MarkerSection;
+declare function ulid(seedTime?: number): string;
 /**
- * Build the final markdown body by replacing the BASOU:GENERATED region.
+ * Generate a prefixed Basou ID, e.g. `ses_01HXABCDEF1234567890ABCDEF`.
  *
- * - `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 return type preserves the prefix as a template literal type so that
+ * downstream zod schemas can narrow an `IdPrefix` parameter through the API.
  *
- * The caller passes `fileLabel` (e.g. `"handoff.md"` or `"decisions.md"`)
- * so the error message is informative without leaking an absolute path.
+ * 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.
  */
-declare function renderWithMarkers(existing: string | null, generated: string, fileLabel: string): string;
-
+declare function prefixedUlid<P extends IdPrefix>(prefix: P): PrefixedId<P>;
 /**
- * Options for {@link importSessionFromJson}. All fields are optional.
+ * Check whether the given string is a valid prefixed Basou ID.
  *
- * - `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.
+ * 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.
+ *
+ * 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.
  */
-type ImportSessionOptions = {
-    labelOverride?: string;
-    taskIdOverride?: string;
-    dryRun?: boolean;
-};
+declare function isValidPrefixedId(value: string): 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.
+ * Task lifecycle states.
  *
- * `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.
+ * 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.
  */
-type ImportSessionResult = {
-    sessionId: PrefixedId<"ses">;
-    eventCount: number;
-    finalStatus: SessionStatus;
-    finalSourceKind: SessionSourceKind;
-    pathSanitizeReport: {
-        relatedFiles: number;
-        workingDirectoryRewritten: boolean;
-    };
-};
+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>;
 /**
- * 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.
+ * Schema for the YAML front matter of `.basou/tasks/<task_id>.md`.
  *
- * 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.
+ * 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 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
@@ -2374,17 +2399,95 @@ type ArchiveTaskResult = {
  *   4. Ensure the archive directory exists.
  *   5. Rename main/<id>.md to archive/<id>.md (= atomic on the same fs).
  *
- * Failure modes after step 2 surface as
- * {@link TaskWriteAfterEventError} with `phase: "archive"`; the operator
- * is told the event is durable but the on-disk move is incomplete and
- * must be resolved manually (typically by rerunning `task archive`).
+ * Failure modes after step 2 surface as
+ * {@link TaskWriteAfterEventError} with `phase: "archive"`; the operator
+ * is told the event is durable but the on-disk move is incomplete and
+ * must be resolved manually (typically by rerunning `task archive`).
+ */
+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. `直近の変更ファイル`: the most recent session's `related_files`, 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 archiveTask(input: ArchiveTaskInput): Promise<ArchiveTaskResult>;
+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,98 +2595,6 @@ 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.
- *
- * 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>;
-
-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;
-};
-/**
- * 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.
- *
- * 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 renderDecisions(input: DecisionsRendererInput): Promise<DecisionsRendererResult>;
-
 /**
  * Internal abstraction over child-process execution.
  *
@@ -2622,283 +2633,669 @@ type RunOptions = {
      */
     readonly env?: NodeJS.ProcessEnv;
     /**
-     * External cancellation. Aborting the signal triggers a two-stage
-     * kill (SIGTERM, then SIGKILL after a short grace period).
+     * External cancellation. Aborting the signal triggers a two-stage
+     * kill (SIGTERM, then SIGKILL after a short grace period).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Internal timeout in milliseconds. Must be a positive finite number.
+     * Triggers the same two-stage kill as `signal`.
+     */
+    readonly timeout_ms?: number;
+    /**
+     * Optional input written to the child's stdin. The pipe is closed
+     * after the value is written. Incompatible with `capture: "none"`.
+     */
+    readonly stdin?: string | Buffer;
+    /**
+     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
+     */
+    readonly capture?: CaptureMode;
+    /**
+     * Invoked synchronously immediately after the child has been spawned,
+     * before the runner waits for completion. Callers use this to retain a
+     * reference for parent-side cleanup (e.g. an `exit` hook that SIGKILLs
+     * the child if the parent is forcibly terminated). The runner takes no
+     * action if the callback throws.
+     */
+    readonly onSpawn?: (child: ChildProcess) => void;
+};
+type RunResult = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** `null` when the process was killed by a signal. */
+    readonly exit_code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** ISO 8601 timestamp captured before spawn. */
+    readonly started_at: string;
+    /** ISO 8601 timestamp captured on the `close` event. */
+    readonly ended_at: string;
+    readonly duration_ms: number;
+    readonly pid: number | null;
+};
+type ProcessRunner = {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+};
+
+/**
+ * Spawn-based ProcessRunner implementation.
+ *
+ * Behavior:
+ * - `shell: false` and `detached: false`. The process group is not
+ *   detached, but the OS does not guarantee the child is reaped when
+ *   the parent terminates abruptly; callers handle SIGINT/SIGTERM/exit
+ *   hooks themselves.
+ * - `capture: "buffer"` (default): `stdio: ['pipe', 'pipe', 'pipe']`,
+ *   stdout / stderr are decoded as UTF-8 and accumulated as full
+ *   strings (no streaming callbacks).
+ * - `capture: "none"`: `stdio: ['inherit', 'inherit', 'inherit']`, the
+ *   child writes directly to the parent terminal in real time and
+ *   `RunResult.stdout` / `stderr` are empty strings. `stdin` is
+ *   incompatible with this mode (the child has no writable stdin pipe)
+ *   and the combination is rejected before spawn.
+ * - `timeout_ms` and `AbortSignal` both trigger a two-stage kill:
+ *   `SIGTERM`, then `SIGKILL` after `DEFAULT_KILL_GRACE_MS` (5_000 ms).
+ * - A non-zero `exit_code` does not throw; it is returned via
+ *   `RunResult`. Spawn-time errors throw with a pathless message and
+ *   the original error attached as `cause`.
+ *
+ * Error message contract: messages never include `cwd` or absolute
+ * command paths. The original errno (and any nested wrapping) is
+ * preserved on `Error.cause`, allowing callers to classify with
+ * `findErrorCode` when needed.
+ */
+declare class ChildProcessRunner implements ProcessRunner {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+}
+
+/**
+ * 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>;
+
+/**
+ * Gap longer than this between two consecutive engagement timestamps is treated
+ * as idle and not credited as active time. A deliberately coarse heuristic: a
+ * focus / billable-attention proxy, NOT a measure of model compute. 5 minutes.
+ */
+declare const ACTIVE_GAP_CAP_MS: number;
+/** A wall-clock range expressed as ISO-8601 strings (for persistence). */
+type IsoInterval = {
+    start: string;
+    end: string;
+};
+
+type WorkStatsInput = {
+    paths: BasouPaths;
+    /** Shared clock; running sessions are measured up to this instant. */
+    now: Date;
+    /**
+     * IANA timezone used to bucket the per-day breakdown (logs are UTC, so a
+     * billing day needs an explicit zone). Defaults to the host's local zone;
+     * injectable for deterministic tests.
      */
-    readonly signal?: AbortSignal;
+    timeZone?: string;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+};
+/** Which measures are meaningful for a given session / source. */
+type MeasureAvailability = {
+    /** Always true (started_at + now bound the span). */
+    span: boolean;
     /**
-     * Internal timeout in milliseconds. Must be a positive finite number.
-     * Triggers the same two-stage kill as `signal`.
+     * `commandTimeMs` reflects real shell time. False for `claude-code-import`,
+     * whose transcript carries no per-command duration (recorded as 0).
      */
-    readonly timeout_ms?: number;
+    commandTime: boolean;
+    /** At least one active interval could be measured (stored or event-derived). */
+    activeTime: boolean;
+    /** Token totals were captured (model-usage metrics present). */
+    tokens: boolean;
+};
+/** Token rollup. Zero when not captured; `reasoning` is Codex-only. */
+type TokenTotals = {
+    output: number;
+    input: number;
+    cached: number;
+    reasoning: number;
+};
+/** How a session's active time was derived. */
+type ActiveTimeBasis = "engaged-turns" | "events";
+type SessionWorkStats = {
+    sessionId: string;
+    label: string | undefined;
+    status: SessionStatus;
+    sourceKind: SessionSourceKind;
+    startedAt: string;
+    endedAt: string | undefined;
+    /** ended_at absent: span is measured to `now`. */
+    open: boolean;
+    sessionSpanMs: number;
+    commandTimeMs: number;
+    activeTimeMs: number;
     /**
-     * Optional input written to the child's stdin. The pipe is closed
-     * after the value is written. Incompatible with `capture: "none"`.
+     * How `activeTimeMs` / `activeIntervals` were derived: `engaged-turns` from
+     * the engagement timestamps stored at import (captures conversation), or
+     * `events` from the action-event stream (live sessions and pre-v2 imports).
      */
-    readonly stdin?: string | Buffer;
+    activeTimeBasis: ActiveTimeBasis;
     /**
-     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
+     * Merged active wall-clock ranges. Their summed duration equals
+     * `activeTimeMs`; the aggregator unions them across sessions so overlapping
+     * (concurrent) work is not double-counted in billable totals.
      */
-    readonly capture?: CaptureMode;
+    activeIntervals: IsoInterval[];
+    commandCount: number;
+    fileChangedCount: number;
+    decisionCount: number;
+    eventCount: number;
+    tokens: TokenTotals;
+    availability: MeasureAvailability;
+    /** ended_at < started_at (clock skew): span was clamped to 0. */
+    spanClamped: boolean;
+    /** events.jsonl could not be read: action / time counts are 0 + untrustworthy. */
+    eventsUnreadable: boolean;
+};
+type SourceWorkStats = {
+    sourceKind: SessionSourceKind;
+    sessionCount: number;
+    sessionSpanMs: number;
+    commandTimeMs: number;
+    activeTimeMs: number;
+    commandCount: number;
+    fileChangedCount: number;
+    decisionCount: number;
+    eventCount: number;
+    tokens: TokenTotals;
+    /** Every session of this kind reports real command time. */
+    commandTimeReliable: boolean;
+    /** At least one session of this kind captured token totals. */
+    tokensAvailable: boolean;
+};
+type StatusCount = {
+    status: SessionStatus;
+    count: number;
+};
+/**
+ * One calendar day of the time x volume billing view. `billableActiveTimeMs` is
+ * the union of active intervals starting on this date (so per-day sums to the
+ * de-duplicated workspace total); volume is attributed to each session's
+ * `started_at` date.
+ */
+type DayWorkStats = {
+    /** Calendar date `YYYY-MM-DD` in the report timezone. */
+    date: string;
+    billableActiveTimeMs: number;
+    sessionCount: number;
+    commandCount: number;
+    fileChangedCount: number;
+    decisionCount: number;
+    tokens: TokenTotals;
+};
+type WorkStatsTotals = {
+    sessionCount: number;
+    openSessionCount: number;
+    sessionSpanMs: number;
+    commandTimeMs: number;
+    /** Naive sum of per-session active time; double-counts overlapping sessions. */
+    activeTimeMs: number;
     /**
-     * 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.
+     * Billable active time: the UNION of every session's active intervals, so
+     * concurrent sessions do not double-count human wall-clock. Equals
+     * `activeTimeMs` when no sessions overlap, and is smaller when they do.
      */
-    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;
+    billableActiveTimeMs: number;
+    commandCount: number;
+    fileChangedCount: number;
+    decisionCount: number;
+    eventCount: number;
+    tokens: TokenTotals;
+    /** No `claude-code-import` sessions present, so command time is workspace-wide real. */
+    commandTimeReliable: boolean;
+    tokensAvailable: boolean;
 };
-type ProcessRunner = {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+type WorkStatsResult = {
+    generatedAt: string;
+    /** Idle-gap cap applied to active time (methodology lock). */
+    activeGapCapMs: number;
+    /** IANA timezone used to bucket {@link WorkStatsResult.byDay}. */
+    timeZone: string;
+    totals: WorkStatsTotals;
+    /** Per session, started_at ascending (loadSessionEntries order). */
+    sessions: SessionWorkStats[];
+    bySource: SourceWorkStats[];
+    byStatus: StatusCount[];
+    /** Per-day time x volume billing view, date ascending. */
+    byDay: DayWorkStats[];
 };
+/**
+ * Aggregate work + engaged-time across the workspace's sessions.
+ *
+ * Honesty note: this returns a LABELED SET of measures, not one number. Token
+ * volume (when captured) is the most direct "how much the AI produced" signal.
+ * The time measures are proxies, ordered from most to least billing-relevant:
+ *
+ * - `billableActiveTimeMs` (totals) is the headline for billing human harness
+ *   labor: the UNION of every session's active intervals, so two sessions run
+ *   concurrently do not bill the same wall-clock twice. `activeTimeMs` is the
+ *   naive sum, kept only to expose the overlap delta.
+ * - Per-session active time is derived from the session's ENGAGED series. For
+ *   imported sessions this is the genuine engagement timestamps captured at
+ *   import (conversation turns plus action events), so design discussion that
+ *   produced few tool calls is still counted; idle gaps over `ACTIVE_GAP_CAP_MS`
+ *   (5 min) are not credited. Live sessions and pre-v2 imports lack that signal
+ *   and fall back to the action-event stream (`activeTimeBasis: "events"`).
+ * - `sessionSpanMs` overcounts (includes idle) and `commandTimeMs` is
+ *   shell-execution only (0 for `claude-code-import`); both are kept as context.
+ *
+ * The per-day view buckets the union intervals by `timeZone` (logs are UTC, so
+ * a billing day needs an explicit zone). A union interval crossing local
+ * midnight is attributed to its start day; per-day time still sums to the
+ * billable total. Availability flags let callers caveat each measure.
+ *
+ * Session enumeration goes through {@link loadSessionEntries} (the handoff /
+ * decisions path), so `session.yaml`-broken sessions are skipped consistently.
+ */
+declare function computeWorkStats(input: WorkStatsInput): Promise<WorkStatsResult>;
+/**
+ * Compute one session's work stats from its inner record + event list. Pure
+ * and exported so a single-session surface (e.g. `basou session show`) can
+ * reuse the exact same measures the workspace aggregator produces.
+ */
+declare function sessionWorkStatsFromEvents(sessionId: string, inner: Session["session"], events: ReadonlyArray<Event>, now: Date, eventsUnreadable?: boolean): SessionWorkStats;
 
+type AppendBasouGitignoreResult = {
+    /** True if the block was appended (or the file was newly created). */
+    readonly appended: boolean;
+};
 /**
- * Spawn-based ProcessRunner implementation.
+ * Append Basou's default `.gitignore` block to `repositoryRoot/.gitignore`.
+ *
+ * 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.
  *
  * 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`.
+ * - 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.
  *
- * 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.
+ * 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 class ChildProcessRunner implements ProcessRunner {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
-}
+declare function appendBasouGitignore(repositoryRoot: string): Promise<AppendBasouGitignoreResult>;
 
 /**
- * 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.
+ * 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 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>;
+};
+/**
+ * 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.
  *
- * `ahead` / `behind` are omitted when there is no remote or no upstream
- * tracking; the schema declares both as optional non-negative integers.
+ * 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.
+ *
+ * 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.
  */
-type GitSnapshot = Omit<GitSnapshotEvent, "schema_version" | "id" | "session_id" | "occurred_at" | "source" | "type">;
+declare function acquireLock(paths: BasouPaths, scope: LockScope, resourceId: string): Promise<LockHandle>;
+
 /**
- * Resolve the absolute path of the Git repository root that contains `cwd`.
- * Equivalent to `git rev-parse --show-toplevel`.
+ * 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.
  *
- * 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.
+ * Refuses to overwrite an existing manifest unless `force: true`.
+ */
+declare function writeManifest(paths: BasouPaths, manifest: Manifest, options?: {
+    force?: boolean;
+}): Promise<void>;
+/**
+ * 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.
  *
- * Pathless contract: the thrown message never embeds `cwd` or any absolute
- * path; native errors are kept on `error.cause` for verbose surfacing.
+ * 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.
  */
-declare function resolveRepositoryRoot(cwd: string): Promise<string>;
+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 `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).
+ * 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.
  *
- * 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
@@ -2906,4 +3303,4 @@ declare function parseDuration(input: string): number;
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { type AdapterOutputEvent, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type CaptureMode, ChildProcessRunner, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, IsoTimestampSchema, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type NoteAddedEvent, type PrefixedId, type ProcessRunner, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReplayOptions, type ReplayWarning, type RiskLevel, RiskLevelSchema, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, StatusSchema, type StatusSnapshot, type SuspectReason, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, WorkspaceIdSchema, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildStatusSnapshot, classifySuspect, claudeCodeAdapterMetadata, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, findErrorCode, getDiff, getSnapshot, importSessionFromJson, isLazyExpired, isValidPrefixedId, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, overwriteYamlFile, parseDuration, parseMarkers, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, reconcileAllTasks, reconcileTask, refreshTaskLinkedSessions, renderDecisions, renderHandoff, renderWithMarkers, replayEvents, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, summarizeAdapterOutput, tryRemoteUrl, ulid, updateTaskStatusWithEvent, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, ChildProcessRunner, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, IsoTimestampSchema, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type PrefixedId, type ProcessRunner, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReplayOptions, type ReplayWarning, type RiskLevel, RiskLevelSchema, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildStatusSnapshot, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, findErrorCode, getDiff, getSnapshot, importSessionFromJson, isLazyExpired, isValidPrefixedId, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, overwriteYamlFile, parseDuration, parseMarkers, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, reconcileAllTasks, reconcileTask, refreshTaskLinkedSessions, renderDecisions, renderHandoff, renderWithMarkers, replayEvents, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, sessionWorkStatsFromEvents, summarizeAdapterOutput, tryRemoteUrl, ulid, updateTaskStatusWithEvent, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };