@basou/core 0.35.1 → 0.36.0

package/dist/index.d.ts

@@ -579,6 +579,9 @@ declare const SessionImportPayloadSchema: z.ZodObject<{
         type: z.ZodLiteral<"review_recorded">;
         reviewer: z.ZodString;
         target: z.ZodString;
+        repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        repos_resolved: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        commits: z.ZodOptional<z.ZodArray<z.ZodString>>;
         verdict: z.ZodOptional<z.ZodEnum<{
             pass: "pass";
             "needs-attention": "needs-attention";
@@ -1325,6 +1328,9 @@ declare const ReviewRecordedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"review_recorded">;
     reviewer: z.ZodString;
     target: z.ZodString;
+    repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    repos_resolved: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    commits: z.ZodOptional<z.ZodArray<z.ZodString>>;
     verdict: z.ZodOptional<z.ZodEnum<{
         pass: "pass";
         "needs-attention": "needs-attention";
@@ -1614,6 +1620,9 @@ declare const EventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"review_recorded">;
     reviewer: z.ZodString;
     target: z.ZodString;
+    repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    repos_resolved: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    commits: z.ZodOptional<z.ZodArray<z.ZodString>>;
     verdict: z.ZodOptional<z.ZodEnum<{
         pass: "pass";
         "needs-attention": "needs-attention";
@@ -5983,6 +5992,14 @@ declare function renderReport(input: ReportRendererInput): Promise<ReportRendere
  *  - `unknown`       the repo or time could not be derived; abstain rather than
  *                    guess (an abstention is never counted as a clear).
  *
+ * A `review_recorded` event (written by `basou review record`) is a SELF-REPORT:
+ * the agent's own claim that a review ran, with nothing corroborating it. Such a
+ * record is bound to a unit by the repo paths it names and surfaced as a label,
+ * but it NEVER changes that unit's verdict — a gap stays a gap, a candidate
+ * stays a candidate — otherwise an empty record would become a way to make the
+ * gap count go down, the same weakness the Stop-gate has. It re-labels; it does
+ * not clear.
+ *
  * It reads only captured provenance and writes nothing.
  */
 type ReviewGapVerdict = "omission" | "near_unbound" | "candidate" | "unknown";
@@ -5995,6 +6012,28 @@ type CitedReview = {
     files: string[];
     endedAt: string | null;
 };
+/**
+ * A `review_recorded` self-report bound to a unit by the repo paths it named.
+ * Carries no corroboration: it is what the agent said it did, not what the
+ * capture observed.
+ */
+type SelfReportedReview = {
+    sessionId: string;
+    eventId: string;
+    reviewer: string;
+    target: string;
+    recordedAt: string;
+    /** Commit SHAs the record claimed to cover; display only, never a binding key. */
+    commits: string[];
+    /**
+     * The record was written after this unit's first commit, so it cannot have
+     * gated the work. Surfaced rather than hidden — a claim made after the fact is
+     * still the operator's own note about what happened, and the label can never
+     * reduce the gap count — but kept distinguishable, because when a record was
+     * written is part of what the operator is judging.
+     */
+    recordedAfterCommit: boolean;
+};
 /** One unit of work (a committing session's commits in one repo) and its verdict. */
 type ReviewGapUnit = {
     repo: string;
@@ -6006,6 +6045,33 @@ type ReviewGapUnit = {
     verdict: ReviewGapVerdict;
     /** For `candidate` / `near_unbound`: the review sessions considered. */
     reviews: CitedReview[];
+    /**
+     * `review_recorded` self-reports naming this repo in the window. Present on
+     * every repo-keyed unit; it re-labels the unit and NEVER alters `verdict`, so
+     * a self-reported gap is still a gap.
+     */
+    selfReports: SelfReportedReview[];
+};
+/** Recorded reviews that reached no unit of work, broken down by cause. */
+type UnattachedSelfReports = {
+    total: number;
+    /** The record named no repository at all. */
+    noRepos: number;
+    /**
+     * At least one repository it named could not be verified as a repo root on
+     * this machine. ANY unverifiable entry puts the record here, even alongside
+     * one that resolved: a half-checkable claim is refused whole, so that
+     * everything that does get paired was checkable in full.
+     */
+    unresolvableRepo: number;
+    /** It named a resolvable repository, but no unit of work fell in the window. */
+    noMatchingUnit: number;
+    /**
+     * Work WAS captured in the window, but the unit's own repository path could
+     * not be verified, so the pairing could not be checked either way. Distinct
+     * from {@link noMatchingUnit}, which would deny that the work exists.
+     */
+    unverifiableUnit: number;
 };
 type ReviewGapRepoSummary = {
     repo: string;
@@ -6014,6 +6080,8 @@ type ReviewGapRepoSummary = {
     nearUnboundUnits: number;
     candidateUnits: number;
     unknownUnits: number;
+    /** Of the units with no bound trail, how many carry a self-report only. */
+    selfReportedGapUnits: number;
 };
 type ReviewGapsSummary = {
     generatedAt: string;
@@ -6027,6 +6095,30 @@ type ReviewGapsSummary = {
     candidates: ReviewGapUnit[];
     /** Units whose repo/time could not be derived from the captured command; abstained, not cleared. */
     unknowns: ReviewGapUnit[];
+    /**
+     * Recorded reviews that changed nothing in this report — the answer to "I ran
+     * `basou review record` and the omission is still there". Reported with the
+     * reason for each, because basou must not assert a cause it has not
+     * established; "no `repos` field" and "a `repos` that does not resolve" are
+     * different mistakes with different fixes.
+     *
+     * Unlike {@link unknowns} this is NOT suppressed under a `--repo` scope, and
+     * attachment is computed against every unit rather than the scoped ones. It is
+     * a caveat about the tool's own input handling, not repo-dimensioned data, and
+     * a completeness caveat that disappears under a filter is how silence starts
+     * looking like success again — the very failure this surfacer exists to catch.
+     */
+    unattachedSelfReports: UnattachedSelfReports;
+    /**
+     * How many (record, unit) pairings fell inside a unit's window but could not
+     * be checked, because that unit's own repository path was never verified.
+     *
+     * Counted per PAIRING, not per record, and reported even when the record
+     * attached to some other unit: {@link unattachedSelfReports} only speaks for
+     * records that changed nothing at all, so a record that landed once and was
+     * refused elsewhere would otherwise leave the refusal invisible.
+     */
+    refusedPairings: number;
     /** Newest captured commit considered; commits not yet imported are invisible. */
     newestCommitAt: string | null;
 };
@@ -6057,6 +6149,38 @@ type ReviewGapsSummary = {
  * process lifetime.
  */
 declare function normalizeRepoPath(p: string | null | undefined): string | null;
+/** Why a hand-typed repository path cannot become a binding key. */
+type RepoPathProblem = "relative" | "absent" | "not_a_repo_root";
+/** A `repos` entry that cannot bind, and why. */
+type UnbindableRepo = {
+    repo: string;
+    index: number;
+    problem: RepoPathProblem;
+};
+/**
+ * Strict repo-root resolution for HAND-TYPED input (a record's `repos`), as
+ * opposed to {@link normalizeRepoPath}, which reads paths basou itself captured.
+ *
+ * The difference is the string fallback. `normalizeRepoPath` keeps one for
+ * captured data: a historical `cd` target whose repo has since moved is still
+ * the best key available, and refusing it would lose an observation basou
+ * genuinely made. Typed input has no such claim on the benefit of the doubt — a
+ * relative path, a typo, or a subdirectory would mint a key that no commit can
+ * ever match, and the record would then be accepted, stored, and silently
+ * unbindable forever. So this verifies against the disk and returns null
+ * otherwise.
+ *
+ * The asymmetry runs the safe way: everything this accepts, `normalizeRepoPath`
+ * resolves to the same key, so a record the writer took is a record the reader
+ * can bind.
+ */
+declare function resolveRepoRoot(p: string | null | undefined): string | null;
+/**
+ * The `repos` entries that could never bind to a unit of work, for the writer to
+ * reject before the record is stored. Sharing {@link classifyRepoPath} with the
+ * reader is the point: the writer must not accept a path the reader cannot use.
+ */
+declare function findUnbindableRepos(repos: readonly string[]): UnbindableRepo[];
 /**
  * Short repo key (the final path segment) for DISPLAY and `--scope` matching.
  * Binding uses {@link normalizeRepoPath} to avoid basename collisions; this is
@@ -6103,6 +6227,19 @@ type ReviewRecordInput = {
     reviewer: string;
     /** What was reviewed (e.g. "working-tree", a git ref, "PR #145"). Required. */
     target: string;
+    /**
+     * Repository paths the review examined. Optional, but it is the ONLY thing
+     * that can bind this record to the reviewed repo: the record lands in an
+     * ad-hoc session whose location is the planning repo it was written from, not
+     * the repo under review. Without it `review-gaps` cannot associate the record
+     * with a unit of work.
+     */
+    repos?: string[];
+    /**
+     * Commit SHAs the review examined. Optional; recorded as the reviewer's own
+     * claim about coverage.
+     */
+    commits?: string[];
     /** Overall outcome. Optional. */
     verdict?: "pass" | "needs-attention" | "fail";
     /** Findings surfaced by the review. Optional. */
@@ -6133,6 +6270,13 @@ declare function buildReviewRecordedEvent(input: {
     sessionId: PrefixedId<"ses">;
     occurredAt: string;
     review: ReviewRecordInput;
+    /**
+     * The canonical repository roots `review.repos` resolved to on this machine.
+     * A CALLER-DERIVED value, not part of the piped input: what a path resolves to
+     * is something basou observes, and the whole point of keeping it is that the
+     * author's spelling may be a symlink whose target changes later.
+     */
+    reposResolved?: string[];
 }): Event;
 /** Ad-hoc session label for a recorded review: `Ad-hoc review: <reviewer> -> <target>`. */
 declare function buildReviewRecordLabel(review: ReviewRecordInput): string;
@@ -6722,4 +6866,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AnchorStarterInput, type AnchorStarterRepo, 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 BuildStopHookCommandOptions, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeSettings, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexCommandLookup, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, 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 IncompleteWiring, 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 MissingCanonical, type NoteAddedEvent, ORIENTATION_END, ORIENTATION_START, 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 PresetStrings, type ProcessRunner, type PublishKind, type PublishTarget, REVIEW_RECORD_NO_INPUT_HINT, 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 RepoInstructions, 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 RetrofitAction, type RetrofitAgentsState, type RetrofitFacts, type RetrofitPlan, type RetrofitReason, type ReviewBlocked, type ReviewFinding, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type ReviewGateResult, type ReviewGateSilentReason, type ReviewRecordBlockedInput, type ReviewRecordFindingInput, type ReviewRecordInput, type ReviewRecordedEvent, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STOP_HOOK_TIMEOUT_SECONDS, 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 SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookRemoval, type StopHookSilentReason, type StopHookUpsert, 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 ViewLanguage, type ViewLinkState, type ViewPresetInput, type ViewPresetRepo, type ViewRepoFact, type ViewStrayUnknown, type ViewStrings, type ViewWiringFacts, type WiringCollision, type WiringConflict, type WiringDriftSummary, 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, buildReviewRecordLabel, buildReviewRecordedEvent, buildStatusSnapshot, buildStopHookCommand, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifyRetrofit, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexAdapterMetadata, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findBasouStopHookCommand, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, instructionMode, isBasouStopHookCommand, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, parseReviewRecordInput, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, presetStrings, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, removeStopHook, renderAnchorStarter, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderViewPresetBlock, renderWithMarkers, replayEvents, resolveAnchorContentLanguage, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveCodexCommand, resolveRepoContentLanguage, resolveRepositoryRoot, resolveSessionId, resolveTaskId, resolveViewLanguage, resolveViewLanguageFromPaths, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, seedMarkers, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, summarizeWiringDrift, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, upsertStopHook, verifyEventsChain, viewStrings, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AnchorStarterInput, type AnchorStarterRepo, 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 BuildStopHookCommandOptions, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeSettings, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexCommandLookup, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, 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 IncompleteWiring, 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 MissingCanonical, type NoteAddedEvent, ORIENTATION_END, ORIENTATION_START, 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 PresetStrings, type ProcessRunner, type PublishKind, type PublishTarget, REVIEW_RECORD_NO_INPUT_HINT, 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 RepoInstructions, type RepoLanguage, type RepoPathProblem, 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 RetrofitAction, type RetrofitAgentsState, type RetrofitFacts, type RetrofitPlan, type RetrofitReason, type ReviewBlocked, type ReviewFinding, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type ReviewGateResult, type ReviewGateSilentReason, type ReviewRecordBlockedInput, type ReviewRecordFindingInput, type ReviewRecordInput, type ReviewRecordedEvent, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STOP_HOOK_TIMEOUT_SECONDS, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type SelfReportedReview, 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 SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookRemoval, type StopHookSilentReason, type StopHookUpsert, 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 UnattachedSelfReports, type UnbindableRepo, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLanguage, type ViewLinkState, type ViewPresetInput, type ViewPresetRepo, type ViewRepoFact, type ViewStrayUnknown, type ViewStrings, type ViewWiringFacts, type WiringCollision, type WiringConflict, type WiringDriftSummary, 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, buildReviewRecordLabel, buildReviewRecordedEvent, buildStatusSnapshot, buildStopHookCommand, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifyRetrofit, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexAdapterMetadata, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findBasouStopHookCommand, findErrorCode, findReviewGaps, findUnbindableRepos, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, instructionMode, isBasouStopHookCommand, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, parseReviewRecordInput, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, presetStrings, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, removeStopHook, renderAnchorStarter, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderViewPresetBlock, renderWithMarkers, replayEvents, resolveAnchorContentLanguage, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveCodexCommand, resolveRepoContentLanguage, resolveRepoRoot, resolveRepositoryRoot, resolveSessionId, resolveTaskId, resolveViewLanguage, resolveViewLanguageFromPaths, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, seedMarkers, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, summarizeWiringDrift, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, upsertStopHook, verifyEventsChain, viewStrings, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };

package/dist/index.js

@@ -1534,6 +1534,9 @@ var ReviewRecordedEventSchema = BaseEventSchema.extend({
   type: z3.literal("review_recorded"),
   reviewer: z3.string().min(1),
   target: z3.string().min(1),
+  repos: z3.array(z3.string().min(1)).optional(),
+  repos_resolved: z3.array(z3.string().min(1)).optional(),
+  commits: z3.array(z3.string().min(1)).optional(),
   verdict: z3.enum(["pass", "needs-attention", "fail"]).optional(),
   findings: z3.array(ReviewFindingSchema).optional(),
   blocked: z3.array(ReviewBlockedSchema).optional()
@@ -7539,6 +7542,29 @@ function normalizeRepoPath(p) {
   if (/-workspace$/.test(seg) || seg.includes("$")) return null;
   return s;
 }
+function recordRepoKey(p) {
+  return resolveRepoRoot(p);
+}
+function resolveRepoRoot(p) {
+  return classifyRepoPath(p).resolved;
+}
+function classifyRepoPath(p) {
+  let s = stripQuotes((p ?? "").trim()).replace(/\/+$/, "");
+  if (s.startsWith("~/")) s = homedir2() + s.slice(1);
+  if (s.length === 0 || !isAbsolute2(s)) return { resolved: null, problem: "relative" };
+  const real = resolveRealpath(s);
+  if (real === null) return { resolved: null, problem: "absent" };
+  if (!isRepoRoot(real)) return { resolved: null, problem: "not_a_repo_root" };
+  return { resolved: real, problem: null };
+}
+function findUnbindableRepos(repos) {
+  const out = [];
+  repos.forEach((repo, index) => {
+    const { problem } = classifyRepoPath(repo);
+    if (problem !== null) out.push({ repo, index, problem });
+  });
+  return out;
+}
 function normalizeRepoKey(p) {
   const full = normalizeRepoPath(p);
   return full === null ? null : basename3(full);
@@ -7560,10 +7586,16 @@ function inspectCommand(args) {
   }
   return { files: [...files], examinedDiff };
 }
-function commandRepo(args, cwd) {
+function commandRepoWithProvenance(args, cwd) {
+  const raw = commandRepoPath(args, cwd);
+  return { key: normalizeRepoPath(raw), resolved: resolveRepoRoot(raw) !== null };
+}
+function commandRepoPath(args, cwd) {
   const cd = args.join(" ").match(/\bcd\s+("[^"]+"|'[^']+'|[^\s&]+)\s*&&/);
-  if (cd) return normalizeRepoPath(cd[1]);
-  return normalizeRepoPath(cwd);
+  return cd?.[1] ?? cwd;
+}
+function commandRepo(args, cwd) {
+  return normalizeRepoPath(commandRepoPath(args, cwd));
 }
 function commandFailed(exitCode) {
   return exitCode !== null && exitCode !== 0;
@@ -7585,6 +7617,9 @@ async function findReviewGaps(input) {
   if (input.onWarning !== void 0) loadOpts.onWarning = input.onWarning;
   const entries = await loadSessionEntries(input.paths, loadOpts);
   const reviews = [];
+  const selfReports = [];
+  let noRepos = 0;
+  let unresolvableRepo = 0;
   const workUnits = /* @__PURE__ */ new Map();
   const unknownCommits = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -7596,6 +7631,28 @@ async function findReviewGaps(input) {
       for await (const ev of replayEvents(sessionDir, {
         onWarning: (w) => input.onWarning?.(w, entry.sessionId)
       })) {
+        if (ev.type === "review_recorded") {
+          const recordedAt = Date.parse(ev.occurred_at);
+          const named = ev.repos_resolved !== void 0 && ev.repos_resolved.length > 0 ? ev.repos_resolved : ev.repos ?? [];
+          const keys = named.map((r) => recordRepoKey(r));
+          const repos2 = new Set(keys.filter((r) => r !== null));
+          if (keys.some((k) => k === null) || repos2.size === 0 || Number.isNaN(recordedAt)) {
+            if (named.length === 0) noRepos++;
+            else unresolvableRepo++;
+            continue;
+          }
+          selfReports.push({
+            sessionId: entry.sessionId,
+            eventId: ev.id,
+            reviewer: ev.reviewer,
+            target: ev.target,
+            recordedAt: ev.occurred_at,
+            commits: ev.commits ?? [],
+            at: recordedAt,
+            repos: repos2
+          });
+          continue;
+        }
         if (ev.type !== "command_executed") continue;
         if (commandFailed(ev.exit_code)) continue;
         const at = Date.parse(ev.occurred_at);
@@ -7611,7 +7668,7 @@ async function findReviewGaps(input) {
           continue;
         }
         if (!ev.args.join(" ").includes("git commit")) continue;
-        const repo = commandRepo(ev.args, ev.cwd);
+        const { key: repo, resolved: keyResolved } = commandRepoWithProvenance(ev.args, ev.cwd);
         if (repo === null || Number.isNaN(at)) {
           const list2 = unknownCommits.get(entry.sessionId) ?? [];
           list2.push(Number.isNaN(at) ? null : at);
@@ -7620,7 +7677,7 @@ async function findReviewGaps(input) {
         }
         const byRepo = workUnits.get(entry.sessionId) ?? /* @__PURE__ */ new Map();
         const list = byRepo.get(repo) ?? [];
-        list.push({ repo, at, files: commitFiles(ev.args) });
+        list.push({ repo, at, files: commitFiles(ev.args), keyResolved });
         byRepo.set(repo, list);
         workUnits.set(entry.sessionId, byRepo);
       }
@@ -7635,19 +7692,33 @@ async function findReviewGaps(input) {
   const windowMs = windowHours * 3600 * 1e3;
   const units = [];
   let newestCommit = null;
+  const attachedSelfReports = /* @__PURE__ */ new Set();
+  const refusedForUnit = /* @__PURE__ */ new Set();
+  let refusedPairings = 0;
   for (const [sessionId, byRepo] of workUnits) {
     for (const [repoPath, commits] of byRepo) {
       const label = basename3(repoPath);
-      if (scope !== null && !scope.includes(label)) continue;
       const times = commits.map((c) => c.at).sort((a, b) => a - b);
       const first = times[0] ?? null;
       const last = times[times.length - 1] ?? null;
+      const earliest = first ?? last ?? 0;
+      const latest = last ?? first ?? 0;
+      const unitRepoIsHere = commits.every((c) => c.keyResolved);
+      const inWindow = selfReports.filter(
+        (r) => r.repos.has(repoPath) && r.at >= earliest - windowMs && r.at <= latest + windowMs
+      );
+      const selfBound = unitRepoIsHere ? inWindow : [];
+      if (!unitRepoIsHere) {
+        refusedPairings += inWindow.length;
+        for (const r of inWindow) refusedForUnit.add(r.eventId);
+      }
+      for (const r of selfBound) attachedSelfReports.add(r.eventId);
+      if (scope !== null && !scope.includes(label)) continue;
       if (last !== null) newestCommit = newestCommit === null ? last : Math.max(newestCommit, last);
       const changedFiles = new Set(commits.flatMap((c) => c.files));
-      const before = first ?? last ?? 0;
       const nearby = reviews.filter((r) => {
         if (!r.repos.has(repoPath) || r.endedAt === null) return false;
-        return r.endedAt <= before && r.endedAt >= before - windowMs;
+        return r.endedAt <= earliest && r.endedAt >= earliest - windowMs;
       });
       const bound = nearby.filter((r) => {
         const touched = r.repos.get(repoPath);
@@ -7665,6 +7736,9 @@ async function findReviewGaps(input) {
         firstCommitAt: first === null ? null : new Date(first).toISOString(),
         lastCommitAt: last === null ? null : new Date(last).toISOString(),
         verdict,
+        // Attached after the verdict is computed, and deliberately not an input
+        // to it: a record must never move a unit out of `gaps`.
+        selfReports: selfBound.map((r) => toSelfReportedReview(r, r.at > earliest)),
         reviews: cited.map((r) => ({
           sessionId: r.sessionId,
           examinedDiff: r.repos.get(repoPath)?.examinedDiff ?? false,
@@ -7674,34 +7748,41 @@ async function findReviewGaps(input) {
       });
     }
   }
-  if (scope === null) {
-    for (const [sessionId, times] of unknownCommits) {
-      const valid = times.filter((t) => t !== null).sort((a, b) => a - b);
-      const first = valid[0] ?? null;
-      const last = valid[valid.length - 1] ?? null;
-      if (last !== null) newestCommit = newestCommit === null ? last : Math.max(newestCommit, last);
-      units.push({
-        repo: "(unknown)",
-        sessionId,
-        commitCount: times.length,
-        firstCommitAt: first === null ? null : new Date(first).toISOString(),
-        lastCommitAt: last === null ? null : new Date(last).toISOString(),
-        verdict: "unknown",
-        reviews: []
-      });
+  for (const [sessionId, times] of unknownCommits) {
+    const valid = times.filter((t) => t !== null).sort((a, b) => a - b);
+    const first = valid[0] ?? null;
+    const last = valid[valid.length - 1] ?? null;
+    if (last !== null && scope === null) {
+      newestCommit = newestCommit === null ? last : Math.max(newestCommit, last);
     }
+    units.push({
+      repo: "(unknown)",
+      sessionId,
+      commitCount: times.length,
+      firstCommitAt: first === null ? null : new Date(first).toISOString(),
+      lastCommitAt: last === null ? null : new Date(last).toISOString(),
+      verdict: "unknown",
+      reviews: [],
+      // No repo key, so nothing a record's `repos` could bind to.
+      selfReports: []
+    });
   }
+  const missed = selfReports.filter((r) => !attachedSelfReports.has(r.eventId));
+  const unverifiableUnit = missed.filter((r) => refusedForUnit.has(r.eventId)).length;
+  const noMatchingUnit = missed.length - unverifiableUnit;
   const recentFirst = (a, b) => (Date.parse(b.lastCommitAt ?? "") || 0) - (Date.parse(a.lastCommitAt ?? "") || 0);
-  const repoKeys = [...new Set(units.map((u) => u.repo))].sort();
+  const talliedUnits = scope === null ? units : units.filter((u) => u.verdict !== "unknown");
+  const repoKeys = [...new Set(talliedUnits.map((u) => u.repo))].sort();
   const repos = repoKeys.map((repo) => {
-    const us = units.filter((u) => u.repo === repo);
+    const us = talliedUnits.filter((u) => u.repo === repo);
     return {
       repo,
       units: us.length,
       omissionUnits: us.filter((u) => u.verdict === "omission").length,
       nearUnboundUnits: us.filter((u) => u.verdict === "near_unbound").length,
       candidateUnits: us.filter((u) => u.verdict === "candidate").length,
-      unknownUnits: us.filter((u) => u.verdict === "unknown").length
+      unknownUnits: us.filter((u) => u.verdict === "unknown").length,
+      selfReportedGapUnits: us.filter((u) => isGap(u) && u.selfReports.length > 0).length
     };
   });
   return {
@@ -7709,12 +7790,34 @@ async function findReviewGaps(input) {
     windowHours,
     scope,
     repos,
-    gaps: units.filter((u) => u.verdict === "omission" || u.verdict === "near_unbound").sort(recentFirst),
+    gaps: units.filter(isGap).sort(recentFirst),
     candidates: units.filter((u) => u.verdict === "candidate").sort(recentFirst),
     unknowns: units.filter((u) => u.verdict === "unknown").sort(recentFirst),
+    unattachedSelfReports: {
+      total: noRepos + unresolvableRepo + noMatchingUnit + unverifiableUnit,
+      noRepos,
+      unresolvableRepo,
+      noMatchingUnit,
+      unverifiableUnit
+    },
+    refusedPairings,
     newestCommitAt: newestCommit === null ? null : new Date(newestCommit).toISOString()
   };
 }
+function isGap(u) {
+  return u.verdict === "omission" || u.verdict === "near_unbound";
+}
+function toSelfReportedReview(r, recordedAfterCommit) {
+  return {
+    sessionId: r.sessionId,
+    eventId: r.eventId,
+    reviewer: r.reviewer,
+    target: r.target,
+    recordedAt: r.recordedAt,
+    commits: r.commits,
+    recordedAfterCommit
+  };
+}
 
 // src/review/review-record.ts
 var VALID_VERDICTS = /* @__PURE__ */ new Set(["pass", "needs-attention", "fail"]);
@@ -7723,6 +7826,8 @@ var VALID_BLOCK_REASONS = /* @__PURE__ */ new Set(["spec-deviation", "design-rev
 var ALLOWED_KEYS = /* @__PURE__ */ new Set([
   "reviewer",
   "target",
+  "repos",
+  "commits",
   "verdict",
   "findings",
   "blocked"
@@ -7753,13 +7858,19 @@ function parseReviewRecordInput(raw) {
   for (const key of Object.keys(obj)) {
     if (!ALLOWED_KEYS.has(key)) {
       throw new Error(
-        `Unknown field '${key}'. Allowed: reviewer, target, verdict, findings, blocked.`
+        `Unknown field '${key}'. Allowed: reviewer, target, repos, commits, verdict, findings, blocked.`
       );
     }
   }
   const reviewer = requireNonEmptyString(obj.reviewer, "reviewer");
   const target = requireNonEmptyString(obj.target, "target");
   const out = { reviewer, target };
+  if (obj.repos !== void 0) {
+    out.repos = parseStringArray(obj.repos, "repos");
+  }
+  if (obj.commits !== void 0) {
+    out.commits = parseStringArray(obj.commits, "commits");
+  }
   if (obj.verdict !== void 0) {
     if (typeof obj.verdict !== "string" || !VALID_VERDICTS.has(obj.verdict)) {
       throw new Error(`verdict must be one of pass, needs-attention, fail, got '${obj.verdict}'.`);
@@ -7774,6 +7885,12 @@ function parseReviewRecordInput(raw) {
   }
   return out;
 }
+function parseStringArray(value, field) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} must be an array of strings.`);
+  }
+  return value.map((item, i) => requireNonEmptyString(item, `${field}[${i}]`));
+}
 function parseFindings(value) {
   if (!Array.isArray(value)) {
     throw new Error("findings must be an array of objects.");
@@ -7856,6 +7973,9 @@ function buildReviewRecordedEvent(input) {
     type: "review_recorded",
     reviewer: review.reviewer,
     target: review.target,
+    ...review.repos !== void 0 ? { repos: review.repos } : {},
+    ...input.reposResolved !== void 0 && input.reposResolved.length > 0 ? { repos_resolved: input.reposResolved } : {},
+    ...review.commits !== void 0 ? { commits: review.commits } : {},
     ...review.verdict !== void 0 ? { verdict: review.verdict } : {},
     ...review.findings !== void 0 ? { findings: review.findings } : {},
     ...review.blocked !== void 0 ? { blocked: review.blocked } : {}
@@ -8866,6 +8986,7 @@ export {
   findBasouStopHookCommand,
   findErrorCode,
   findReviewGaps,
+  findUnbindableRepos,
   formatDurationMs,
   genesisHash,
   getDiff,
@@ -8929,6 +9050,7 @@ export {
   resolveClaudeCodeCommand,
   resolveCodexCommand,
   resolveRepoContentLanguage,
+  resolveRepoRoot,
   resolveRepositoryRoot,
   resolveSessionId,
   resolveTaskId,