@basou/core 0.14.1 → 0.16.0

package/dist/index.d.ts

@@ -1573,6 +1573,19 @@ type SessionEntry = {
     session: Session;
     suspect: boolean;
     suspectReason: SuspectReason | null;
+    /**
+     * The trail store this entry was read from. Its `sessions` directory locates
+     * the session's `events.jsonl`, so a federated caller can replay events from
+     * the store the session actually lives in (not the local store). For a plain
+     * local load this is the `paths` passed to {@link loadSessionEntries}.
+     */
+    sourceRoot: BasouPaths;
+    /**
+     * Federation host label from the registry (`~/.basou/hosts.yaml`), or `null`
+     * for the local store. Surfaced by orientation so a merged, multi-host view
+     * can attribute the latest session / decision / next-step to its host.
+     */
+    host: string | null;
 };
 /**
  * Per-session degradation reason emitted by {@link loadSessionEntries.onSkip}.
@@ -1595,6 +1608,28 @@ type LoadSessionEntriesOptions = {
     onWarning?: (warning: ReplayWarning, sessionId: string) => void;
     onSkip?: (sessionId: string, reason: SessionSkipReason) => void;
 };
+/**
+ * A trail store to read in a federated load, tagged with its host label.
+ * `host: null` denotes the local store; a non-null label comes from the host
+ * registry (`~/.basou/hosts.yaml`). `paths` is where that store is reachable
+ * as a local path on this machine (an SSHFS mount, an rsync mirror, etc.) —
+ * basou itself never performs any network I/O to obtain it.
+ */
+type FederatedRoot = {
+    paths: BasouPaths;
+    host: string | null;
+};
+type LoadFederatedOptions = LoadSessionEntriesOptions & {
+    /**
+     * Called when a NON-local root cannot be enumerated (present-but-unreadable
+     * mount, permission error). That root is skipped best-effort so the local
+     * store and other roots still load. The local root (`host: null`) is never
+     * degraded here — its errors propagate, preserving single-store behaviour.
+     * (An absent root path is not an error: {@link enumerateSessionDirs} returns
+     * `[]` on ENOENT, so a dropped mount is simply an empty host.)
+     */
+    onRootUnavailable?: (host: string, error: unknown) => void;
+};
 /**
  * List session directory names under `paths.sessions`, ULID ascending.
  *
@@ -1668,20 +1703,18 @@ declare function classifySuspect(paths: BasouPaths, sessionId: string, session:
     suspect: boolean;
     suspectReason: SuspectReason | null;
 }>;
+declare function loadSessionEntries(paths: BasouPaths, options: LoadSessionEntriesOptions): Promise<SessionEntry[]>;
 /**
- * High-level helper that enumerates session dirs, reads each `session.yaml`,
- * and classifies suspect for `running` sessions in one pass.
- *
- * Per-session degradations are surfaced via `options.onSkip`:
- * - `session_yaml_missing` (ENOENT) and `session_yaml_invalid` (parse or
- *   schema violation): the entry is omitted from the result.
- * - `events_jsonl_unreadable`: the entry is still pushed with `suspect=false`
- *   so callers can render the session row plus a CLI-side warning.
- *
- * `options.now` is taken once and threaded into every {@link classifySuspect}
- * call so age comparisons are consistent across sessions.
+ * Federated load across multiple trail stores. Each root's sessions are tagged
+ * with that root's host label and `sourceRoot`, so a caller replays events from
+ * the store the session lives in. De-duped by `sessionId` (a per-host random
+ * ULID), then by `source.external_id` when present — first occurrence wins, so
+ * pass the local root FIRST to keep it authoritative (e.g. over a re-imported
+ * copy of the same vendor session on another host). A non-local root that
+ * cannot be enumerated is reported via `onRootUnavailable` and skipped; the
+ * local root's errors propagate, matching {@link loadSessionEntries}.
  */
-declare function loadSessionEntries(paths: BasouPaths, options: LoadSessionEntriesOptions): Promise<SessionEntry[]>;
+declare function loadFederatedSessionEntries(roots: ReadonlyArray<FederatedRoot>, options: LoadFederatedOptions): Promise<SessionEntry[]>;
 
 type DecisionsRendererInput = {
     paths: BasouPaths;
@@ -3155,6 +3188,19 @@ type OrientationRendererInput = {
      * reads as a verdict for a supervisor, not developer diagnostics.
      */
     verbose?: boolean;
+    /**
+     * Additional trail stores to MERGE into this orientation, each a local path
+     * (an SSHFS mount / rsync mirror of another host's `.basou`) tagged with a
+     * host label. Absent / empty = local-only (byte-identical to before). basou
+     * performs no network I/O; the operator's existing tooling places these paths.
+     */
+    federatedRoots?: FederatedRoot[];
+    /**
+     * Called when a federated (non-local) host root is present but cannot be
+     * enumerated (e.g. an unreadable mount). That host is skipped; the local
+     * store and other hosts still render. An absent root path is silently empty.
+     */
+    onHostUnavailable?: (host: string, error: unknown) => void;
 };
 type OrientationRendererResult = {
     /** Generated body. orientation.md is overwritten whole (no markers, gitignored). */
@@ -3171,11 +3217,13 @@ type DecisionRecord = {
     title: string;
     occurredAt: string;
     sessionId: string;
+    host: string | null;
 };
 type NoteRecord = {
     body: string;
     sessionId: string;
     occurredAt: string;
+    host: string | null;
 };
 type PendingApproval = {
     id: string;
@@ -3200,11 +3248,13 @@ type SuspectSession = {
     sessionId: string;
     status: string;
     reason: SuspectReason | null;
+    host: string | null;
 };
 type LatestSession = {
     sessionId: string;
     label: string | null;
     status: string;
+    host: string | null;
 };
 type SourceCount = {
     kind: string;
@@ -3249,6 +3299,12 @@ type OrientationSummary = {
     plannedTasks: PlannedTask[];
     pendingApprovals: PendingApproval[];
     suspects: SuspectSession[];
+    /**
+     * Distinct non-local host labels present in the merged set (sorted). Empty
+     * for a local-only orientation. Lets a consumer render the multi-host banner
+     * and the local-only-freshness caveat without re-deriving from sessions.
+     */
+    hosts: string[];
     freshness: {
         /** started_at of the newest non-archived session, or null when none captured. */
         newestStartedAt: string | null;
@@ -5002,15 +5058,26 @@ declare function readManifest(paths: BasouPaths): Promise<Manifest>;
 declare const GENERATED_START = "<!-- BASOU:GENERATED:START -->";
 /** Marker line that ends the auto-generated region. */
 declare const GENERATED_END = "<!-- BASOU:GENERATED:END -->";
+/** Marker line that begins a managed protocol block in a foreign instruction file. */
+declare const PROTOCOL_START = "<!-- BASOU:PROTOCOLS:START -->";
+/** Marker line that ends a managed protocol block. */
+declare const PROTOCOL_END = "<!-- BASOU:PROTOCOLS:END -->";
+/** A start/end marker pair. Both lines are matched whole-line, exact. */
+type Markers = {
+    start: string;
+    end: string;
+};
 /**
  * Result of parsing a markdown body for the BASOU:GENERATED marker region.
  *
  * The spec mandates strict line-level matching (see
  * `docs/spec/generated-markdown.md#102-marker-convention`): a marker is
  * only recognized when an entire line is exactly the marker string.
- * Leading/trailing whitespace, comment compression, and BOM are treated as
- * legacy formats (`no_markers`) so that re-generation refuses to silently
- * overwrite a mismatched manual edit.
+ * Leading/trailing whitespace and comment compression are treated as legacy
+ * formats (`no_markers`) so that re-generation refuses to silently overwrite a
+ * mismatched manual edit. A leading UTF-8 BOM is the one exception: it is
+ * tolerated (stripped for matching, re-prepended on render) so a BOM-prefixed
+ * file round-trips instead of duplicating the block.
  */
 type MarkerSection = {
     kind: "ok";
@@ -5057,11 +5124,13 @@ declare function writeMarkdownFile(filePath: string, body: string): Promise<void
  * - `multiple_pairs`: more than one START or END line.
  * - `wrong_order`: END appears before START.
  *
- * Matching is strict: leading/trailing whitespace, BOM, and comment
- * compression (`<!--BASOU:...-->`) all bypass the marker and are treated
- * as legacy content.
+ * Matching is strict: leading/trailing whitespace and comment compression
+ * (`<!--BASOU:...-->`) bypass the marker and are treated as legacy content. A
+ * leading UTF-8 BOM is the exception: it is stripped before matching and
+ * re-prepended to `before`, so a marker on the first line of a BOM-prefixed
+ * file still matches and the file round-trips.
  */
-declare function parseMarkers(content: string): MarkerSection;
+declare function parseMarkers(content: string, markers?: Markers): MarkerSection;
 /**
  * Build the final markdown body by replacing the BASOU:GENERATED region.
  *
@@ -5073,7 +5142,18 @@ declare function parseMarkers(content: string): MarkerSection;
  * The caller passes `fileLabel` (e.g. `"handoff.md"` or `"decisions.md"`)
  * so the error message is informative without leaking an absolute path.
  */
-declare function renderWithMarkers(existing: string | null, generated: string, fileLabel: string): string;
+declare function renderWithMarkers(existing: string | null, generated: string, fileLabel: string, markers?: Markers): string;
+/**
+ * Remove a marker region from `existing`, returning the body without the block.
+ *
+ * - `no_markers`: returns `existing` unchanged (nothing to remove).
+ * - `ok`: drops both marker lines and the generated region, collapsing the
+ *   single newline that terminated the END marker line so no stray blank line
+ *   is left behind.
+ * - any other parse result: throws a pathless error referencing `fileLabel`
+ *   (mismatched markers must not be silently rewritten).
+ */
+declare function removeMarkerSection(existing: string, fileLabel: string, markers?: Markers): string;
 
 /**
  * Options for {@link importSessionFromJson}. All fields are optional.
@@ -5300,4 +5380,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type ProcessRunner, type PublishKind, type PublishTarget, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoLanguage, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLinkState, type ViewRepoFact, type ViewStrayUnknown, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, finalizeSessionYaml, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FederatedRoot, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadFederatedOptions, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type Markers, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, PROTOCOL_END, PROTOCOL_START, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type ProcessRunner, type PublishKind, type PublishTarget, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoLanguage, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLinkState, type ViewRepoFact, type ViewStrayUnknown, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, finalizeSessionYaml, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };

package/dist/index.js

@@ -1372,7 +1372,8 @@ async function classifySuspect(paths, sessionId, session, now, onWarning) {
   }
   return { suspect: false, suspectReason: null };
 }
-async function loadSessionEntries(paths, options) {
+async function loadEntriesFromRoot(root, options) {
+  const { paths } = root;
   const sessionIds = await enumerateSessionDirs(paths);
   const entries = [];
   for (const sid of sessionIds) {
@@ -1402,10 +1403,50 @@ async function loadSessionEntries(paths, options) {
     } catch {
       options.onSkip?.(sid, "events_jsonl_unreadable");
     }
-    entries.push({ sessionId: sid, session, suspect, suspectReason });
+    entries.push({
+      sessionId: sid,
+      session,
+      suspect,
+      suspectReason,
+      sourceRoot: paths,
+      host: root.host
+    });
   }
   return entries;
 }
+async function loadSessionEntries(paths, options) {
+  return loadEntriesFromRoot({ paths, host: null }, options);
+}
+async function loadFederatedSessionEntries(roots, options) {
+  const out = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  const seenExternal = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    let entries;
+    if (root.host === null) {
+      entries = await loadEntriesFromRoot(root, options);
+    } else {
+      try {
+        entries = await loadEntriesFromRoot(root, options);
+      } catch (error) {
+        options.onRootUnavailable?.(root.host, error);
+        continue;
+      }
+    }
+    for (const entry of entries) {
+      if (seenIds.has(entry.sessionId)) continue;
+      const ext = entry.session.session.source.external_id;
+      if (typeof ext === "string" && ext.length > 0) {
+        const extKey = `${entry.session.session.source.kind}:${ext}`;
+        if (seenExternal.has(extKey)) continue;
+        seenExternal.add(extKey);
+      }
+      seenIds.add(entry.sessionId);
+      out.push(entry);
+    }
+  }
+  return out;
+}
 
 // src/decisions/decisions-renderer.ts
 async function renderDecisions(input) {
@@ -4344,7 +4385,13 @@ async function summarizeOrientation(input) {
   const loadOpts = { now };
   if (input.onSessionSkip !== void 0) loadOpts.onSkip = input.onSessionSkip;
   if (input.onWarning !== void 0) loadOpts.onWarning = input.onWarning;
-  const entries = await loadSessionEntries(input.paths, loadOpts);
+  const entries = input.federatedRoots !== void 0 && input.federatedRoots.length > 0 ? await loadFederatedSessionEntries(
+    [{ paths: input.paths, host: null }, ...input.federatedRoots],
+    {
+      ...loadOpts,
+      ...input.onHostUnavailable !== void 0 ? { onRootUnavailable: input.onHostUnavailable } : {}
+    }
+  ) : await loadSessionEntries(input.paths, loadOpts);
   const decisions = [];
   let latestActivityAt = null;
   let latestNote = null;
@@ -4354,7 +4401,7 @@ async function summarizeOrientation(input) {
     }
   };
   for (const entry of entries) {
-    const sessionDir = join14(input.paths.sessions, entry.sessionId);
+    const sessionDir = join14(entry.sourceRoot.sessions, entry.sessionId);
     const counted = entry.session.session.status !== "archived";
     if (counted) noteActivity(entry.session.session.ended_at ?? entry.session.session.started_at);
     try {
@@ -4366,12 +4413,18 @@ async function summarizeOrientation(input) {
             decisionId: ev.decision_id,
             title: ev.title,
             occurredAt: ev.occurred_at,
-            sessionId: entry.sessionId
+            sessionId: entry.sessionId,
+            host: entry.host
           });
         }
         if (counted && ev.type === "note_added" && ev.kind === "next_step") {
           if (latestNote === null || Date.parse(ev.occurred_at) > Date.parse(latestNote.occurredAt)) {
-            latestNote = { body: ev.body, sessionId: entry.sessionId, occurredAt: ev.occurred_at };
+            latestNote = {
+              body: ev.body,
+              sessionId: entry.sessionId,
+              occurredAt: ev.occurred_at,
+              host: entry.host
+            };
           }
         }
         if (counted) noteActivity(ev.occurred_at);
@@ -4414,7 +4467,8 @@ async function summarizeOrientation(input) {
   const suspects = entries.filter((e) => e.suspect).map((e) => ({
     sessionId: e.sessionId,
     status: e.session.session.status,
-    reason: e.suspectReason
+    reason: e.suspectReason,
+    host: e.host
   }));
   const liveEntries = entries.filter(
     (e) => e.session.session.status !== "archived" && e.session.session.source.kind !== "import"
@@ -4423,7 +4477,8 @@ async function summarizeOrientation(input) {
   const latestSession = latestEntry !== void 0 ? {
     sessionId: latestEntry.sessionId,
     label: latestEntry.session.session.label ?? null,
-    status: latestEntry.session.session.status
+    status: latestEntry.session.session.status,
+    host: latestEntry.host
   } : null;
   const activityEntries = entries.filter((e) => e.session.session.status !== "archived");
   const newest = [...activityEntries].sort(
@@ -4446,6 +4501,9 @@ async function summarizeOrientation(input) {
   const uniqueFiles = new Set(latestFiles);
   const displayed = [...uniqueFiles].sort().slice(0, limit);
   const overflow = Math.max(0, uniqueFiles.size - limit);
+  const hosts = [
+    ...new Set(entries.map((e) => e.host).filter((h) => h !== null))
+  ].sort();
   return {
     generatedAt: input.nowIso,
     sessionCount: entries.length,
@@ -4458,6 +4516,7 @@ async function summarizeOrientation(input) {
     plannedTasks,
     pendingApprovals,
     suspects,
+    hosts,
     freshness: {
       newestStartedAt: newest?.session.session.started_at ?? null,
       newestSource: newest?.session.session.source.kind ?? null,
@@ -4485,11 +4544,15 @@ function formatOrientationBody(summary, opts) {
   const lines = [];
   const now = new Date(summary.generatedAt);
   const newestRel = relativeAge(summary.freshness.newestStartedAt ?? void 0, now);
+  const hostSuffix = (h) => h !== null ? ` @${h}` : "";
   lines.push("# Orientation");
   lines.push("");
   lines.push(
     `> Generated at ${summary.generatedAt} \xB7 sessions ${summary.sessionCount} \xB7 newest ${newestRel} \xB7 pending ${summary.pendingApprovals.length} \xB7 suspect ${summary.suspects.length}`
   );
+  if (summary.hosts.length > 0) {
+    lines.push(`> hosts: local, ${summary.hosts.join(", ")}`);
+  }
   lines.push("");
   lines.push("## \u4ECA\u3069\u3053\u306B\u3044\u308B");
   lines.push("");
@@ -4497,9 +4560,9 @@ function formatOrientationBody(summary, opts) {
     const s = summary.latestSession;
     const sid = shortId(s.sessionId);
     if (s.label !== null && s.label !== "") {
-      lines.push(`- \u6700\u7D42 session: ${s.label} (${s.status}) [${sid}]`);
+      lines.push(`- \u6700\u7D42 session: ${s.label} (${s.status}) [${sid}]${hostSuffix(s.host)}`);
     } else {
-      lines.push(`- \u6700\u7D42 session: ${sid} (${s.status})`);
+      lines.push(`- \u6700\u7D42 session: ${sid} (${s.status})${hostSuffix(s.host)}`);
     }
   } else {
     lines.push("- \u6700\u7D42 session: (no live sessions)");
@@ -4507,7 +4570,9 @@ function formatOrientationBody(summary, opts) {
   if (summary.latestDecision !== null) {
     const dec = summary.latestDecision;
     const decAge = relativeAgeJa(dec.occurredAt, now);
-    lines.push(`- \u76F4\u8FD1\u306E\u5224\u65AD: ${dec.title} [${shortId(dec.decisionId)}] (${decAge})`);
+    lines.push(
+      `- \u76F4\u8FD1\u306E\u5224\u65AD: ${dec.title} [${shortId(dec.decisionId)}] (${decAge})${hostSuffix(dec.host)}`
+    );
     const activityAt = summary.freshness.latestActivityAt;
     if (activityAt !== null && isTrailingStale(activityAt, dec.occurredAt)) {
       lines.push(
@@ -4562,7 +4627,9 @@ function formatOrientationBody(summary, opts) {
     lines.push("- (none)");
   } else {
     for (const e of summary.suspects) {
-      lines.push(`- ${shortId(e.sessionId)} (${e.status}) \u2014 ${suspectText(e.reason)}`);
+      lines.push(
+        `- ${shortId(e.sessionId)} (${e.status}) \u2014 ${suspectText(e.reason)}${hostSuffix(e.host)}`
+      );
     }
   }
   lines.push("");
@@ -4571,7 +4638,7 @@ function formatOrientationBody(summary, opts) {
   if (summary.latestNote !== null) {
     const noteAge = relativeAgeJa(summary.latestNote.occurredAt, now);
     lines.push(
-      `- \u6B21\u306E\u8D77\u70B9 (\u8A18\u9332\u6E08\u307F, ${noteAge}): ${noteSummary(summary.latestNote.body)} [session ${shortId(summary.latestNote.sessionId)}]`
+      `- \u6B21\u306E\u8D77\u70B9 (\u8A18\u9332\u6E08\u307F, ${noteAge}): ${noteSummary(summary.latestNote.body)} [session ${shortId(summary.latestNote.sessionId)}]${hostSuffix(summary.latestNote.host)}`
     );
     const activityAt = summary.freshness.latestActivityAt;
     if (activityAt !== null && isTrailingStale(activityAt, summary.latestNote.occurredAt)) {
@@ -4601,6 +4668,12 @@ function formatOrientationBody(summary, opts) {
   lines.push("## \u3053\u308C\u306F\u6700\u65B0\u304B");
   lines.push("");
   for (const line of freshnessVerdict(summary, opts.staleness, now)) lines.push(line);
+  if (summary.hosts.length > 0) {
+    lines.push("");
+    lines.push(
+      "\u6CE8: \u9BAE\u5EA6\u5224\u5B9A\u306F\u3053\u306E\u30DE\u30B7\u30F3\u306E\u30ED\u30FC\u30AB\u30EB\u30B9\u30C8\u30A2\u306E\u307F\u304C\u5BFE\u8C61\u3067\u3059\u3002\u4ED6\u30DB\u30B9\u30C8\u306E\u53D6\u308A\u3053\u307C\u3057\u306F\u5224\u5B9A\u3067\u304D\u307E\u305B\u3093(\u5404\u30DB\u30B9\u30C8\u3067 basou refresh \u3092\u5B9F\u884C\u3057\u540C\u671F\u3057\u3066\u304F\u3060\u3055\u3044)\u3002"
+    );
+  }
   if (opts.verbose) {
     lines.push("");
     lines.push("<!-- verbose: raw freshness telemetry -->");
@@ -4677,8 +4750,9 @@ function freshnessVerdict(summary, staleness, now) {
       "\u6700\u65B0\u304B\u78BA\u8A8D\u3059\u308B\u306B\u306F `basou refresh` \u3092\u5B9F\u884C\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
     ];
   }
+  const localScope = summary.hosts.length > 0 ? "\u3053\u306E\u30DB\u30B9\u30C8(\u30ED\u30FC\u30AB\u30EB)\u306E" : "";
   const lines = [
-    `\u2705 \u53D6\u308A\u8FBC\u307F\u306F\u6700\u65B0\u3067\u3059\u3002\u6700\u5F8C\u306E\u4F5C\u696D\u306F ${rel}(${tool})\u3002\u672A\u53D6\u308A\u8FBC\u307F\u306E native \u30BB\u30C3\u30B7\u30E7\u30F3\u306F\u3042\u308A\u307E\u305B\u3093\u3002`
+    `\u2705 ${localScope}\u53D6\u308A\u8FBC\u307F\u306F\u6700\u65B0\u3067\u3059\u3002\u6700\u5F8C\u306E\u4F5C\u696D\u306F ${rel}(${tool})\u3002\u672A\u53D6\u308A\u8FBC\u307F\u306E native \u30BB\u30C3\u30B7\u30E7\u30F3\u306F\u3042\u308A\u307E\u305B\u3093\u3002`
   ];
   if (suspectCount > 0) {
     lines.push(`\u305F\u3060\u3057\u8981\u6CE8\u610F\u30BB\u30C3\u30B7\u30E7\u30F3\u304C ${suspectCount} \u4EF6\u3042\u308A\u307E\u3059(\u4E0A\u8A18\u300C\u8981\u6CE8\u610F session\u300D\u53C2\u7167)\u3002`);
@@ -6505,6 +6579,9 @@ function hasErrorCode5(error) {
 import { readFile as readFile9 } from "fs/promises";
 var GENERATED_START = "<!-- BASOU:GENERATED:START -->";
 var GENERATED_END = "<!-- BASOU:GENERATED:END -->";
+var PROTOCOL_START = "<!-- BASOU:PROTOCOLS:START -->";
+var PROTOCOL_END = "<!-- BASOU:PROTOCOLS:END -->";
+var DEFAULT_MARKERS = { start: GENERATED_START, end: GENERATED_END };
 async function readMarkdownFile(filePath) {
   try {
     return await readFile9(filePath, "utf8");
@@ -6520,13 +6597,15 @@ async function writeMarkdownFile(filePath, body) {
     throw new Error("Failed to write markdown file", { cause: error });
   }
 }
-function parseMarkers(content) {
-  const lines = content.split(/\r?\n/);
+function parseMarkers(content, markers = DEFAULT_MARKERS) {
+  const bom = content.charCodeAt(0) === 65279 ? "\uFEFF" : "";
+  const body = bom === "" ? content : content.slice(1);
+  const lines = body.split(/\r?\n/);
   const startLines = [];
   const endLines = [];
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i] === GENERATED_START) startLines.push(i);
-    else if (lines[i] === GENERATED_END) endLines.push(i);
+    if (lines[i] === markers.start) startLines.push(i);
+    else if (lines[i] === markers.end) endLines.push(i);
   }
   if (startLines.length === 0 && endLines.length === 0) return { kind: "no_markers" };
   if (startLines.length === 0) return { kind: "missing_start" };
@@ -6535,30 +6614,30 @@ function parseMarkers(content) {
   const startLineIdx = startLines[0];
   const endLineIdx = endLines[0];
   if (endLineIdx < startLineIdx) return { kind: "wrong_order" };
-  const startOffset = lineStartOffset(content, startLineIdx);
-  const endLineStart = lineStartOffset(content, endLineIdx);
-  const startLineEnd = startOffset + GENERATED_START.length;
-  const endLineEnd = endLineStart + GENERATED_END.length;
-  const before = content.slice(0, startOffset);
-  const afterStartNewline = skipOneNewline(content, startLineEnd);
-  const beforeEndNewline = trimOneNewline(content, endLineStart);
-  const generated = content.slice(afterStartNewline, beforeEndNewline);
-  const after = content.slice(endLineEnd);
+  const startOffset = lineStartOffset(body, startLineIdx);
+  const endLineStart = lineStartOffset(body, endLineIdx);
+  const startLineEnd = startOffset + markers.start.length;
+  const endLineEnd = endLineStart + markers.end.length;
+  const before = bom + body.slice(0, startOffset);
+  const afterStartNewline = skipOneNewline(body, startLineEnd);
+  const beforeEndNewline = trimOneNewline(body, endLineStart);
+  const generated = body.slice(afterStartNewline, beforeEndNewline);
+  const after = body.slice(endLineEnd);
   return { kind: "ok", before, generated, after };
 }
-function renderWithMarkers(existing, generated, fileLabel) {
+function renderWithMarkers(existing, generated, fileLabel, markers = DEFAULT_MARKERS) {
   const normalized = generated.endsWith("\n") ? generated : `${generated}
 `;
   if (existing === null) {
-    return `${GENERATED_START}
-${normalized}${GENERATED_END}
+    return `${markers.start}
+${normalized}${markers.end}
 `;
   }
-  const section = parseMarkers(existing);
+  const section = parseMarkers(existing, markers);
   switch (section.kind) {
     case "ok":
-      return `${section.before}${GENERATED_START}
-${normalized}${GENERATED_END}${section.after}`;
+      return `${section.before}${markers.start}
+${normalized}${markers.end}${section.after}`;
     case "no_markers":
       throw new Error(`Markers missing in ${fileLabel}`);
     case "missing_start":
@@ -6568,6 +6647,22 @@ ${normalized}${GENERATED_END}${section.after}`;
       throw new Error(`Markers mismatched in ${fileLabel}`);
   }
 }
+function removeMarkerSection(existing, fileLabel, markers = DEFAULT_MARKERS) {
+  const section = parseMarkers(existing, markers);
+  switch (section.kind) {
+    case "no_markers":
+      return existing;
+    case "ok": {
+      const after = section.after.replace(/^\r?\n/, "");
+      return section.before + after;
+    }
+    case "missing_start":
+    case "missing_end":
+    case "multiple_pairs":
+    case "wrong_order":
+      throw new Error(`Markers mismatched in ${fileLabel}`);
+  }
+}
 function lineStartOffset(content, lineIdx) {
   if (lineIdx === 0) return 0;
   let offset = 0;
@@ -7008,6 +7103,8 @@ export {
   IsoTimestampSchema,
   JSON_SCHEMA_VERSION,
   ManifestSchema,
+  PROTOCOL_END,
+  PROTOCOL_START,
   RiskLevelSchema,
   STUCK_THRESHOLD_MS,
   SchemaVersionSchema,
@@ -7070,6 +7167,7 @@ export {
   lineHash,
   linkYamlFile,
   loadApproval,
+  loadFederatedSessionEntries,
   loadSessionEntries,
   loadTaskEntries,
   normalizeRepoKey,
@@ -7098,6 +7196,7 @@ export {
   reconcileTask,
   refreshTaskLinkedSessions,
   reimportPreservingId,
+  removeMarkerSection,
   renderDecisions,
   renderHandoff,
   renderOrientation,