@@ -589,7 +589,14 @@ function extractCwd(line: string): string | null {
589589 return null ;
590590}
591591
592- /** @public Pure helper exported for regression tests; identity construction stays beside its comparison. */
592+ /**
593+ * File identity snapshot for one transcript path.
594+ *
595+ * `inodeRaw` carries the decimal `ino` so NTFS file IDs above
596+ * `Number.MAX_SAFE_INTEGER` survive; it is `null` when the raw stat failed.
597+ *
598+ * @public Pure helper exported for regression tests; identity construction stays beside its comparison.
599+ */
593600export function transcriptIdentity (
594601 filePath : string ,
595602 stats : FileSystem . File . Info ,
@@ -611,6 +618,11 @@ export function transcriptIdentity(
611618 } ;
612619}
613620
621+ /**
622+ * Normalizes a stored or freshly read raw inode to a comparable string.
623+ * Anything that is not a non-empty string (missing field on pre-fix records,
624+ * failed stat) becomes `null` and falls back to the numeric check.
625+ */
614626function normalizeInodeRaw ( value : unknown ) : string | null {
615627 return typeof value === "string" && value . length > 0 ? value : null ;
616628}
@@ -626,7 +638,15 @@ interface TranscriptIdentityLike {
626638 readonly birthtimeMs : number | null ;
627639}
628640
629- /** @public Pure helper exported for regression tests; the Windows collision is decided here. */
641+ /**
642+ * Whether two identity snapshots describe the same file.
643+ *
644+ * Records written before the raw ID existed have no `inodeRaw`; they fall
645+ * back to the numeric check so they are not re-imported. When both sides
646+ * carry a raw ID (the Windows case where `inode` is `null`), it must match.
647+ *
648+ * @public Pure helper exported for regression tests; the Windows collision is decided here.
649+ */
630650export function sameTranscriptIdentity (
631651 left : TranscriptIdentityLike ,
632652 right : TranscriptIdentityLike ,
@@ -652,12 +672,7 @@ export function sameTranscriptIdentity(
652672 return true ;
653673}
654674
655- /**
656- * Decimal `ino` for `transcriptIdentity`, preserving NTFS file IDs above
657- * `Number.MAX_SAFE_INTEGER` where Effect's `ino` is `None`. Returns the safe
658- * integer as a string without extra I/O; otherwise stats the path with
659- * bigint enabled. `null` when the file is gone or the ID is unavailable.
660- */
675+ /** Tagged failure for the raw bigint stat in {@link readRawInode}. */
661676class TranscriptInodeStatError extends Schema . TaggedError < TranscriptInodeStatError > ( ) (
662677 "TranscriptInodeStatError" ,
663678 {
@@ -666,6 +681,18 @@ class TranscriptInodeStatError extends Schema.TaggedError<TranscriptInodeStatErr
666681 } ,
667682) { }
668683
684+ /**
685+ * Decimal `ino` for `transcriptIdentity`, preserving NTFS file IDs above
686+ * `Number.MAX_SAFE_INTEGER` where Effect's `ino` is `None`. Returns the safe
687+ * integer as a string without extra I/O; otherwise stats the path with
688+ * bigint enabled. `null` when the file is gone or the ID is unavailable.
689+ *
690+ * The raw stat is path-based while surrounding reads use the opened handle,
691+ * so a replacement racing between the two can only mix metadata from one file
692+ * with the raw ID of another. A mixed identity mismatches (a raw ID names
693+ * exactly one file), so the outcome is always the safe direction — skip or
694+ * re-read — never a false match.
695+ */
669696const readRawInode = (
670697 filePath : string ,
671698 knownIno : Option . Option < number > ,
@@ -726,6 +753,11 @@ export const make = Effect.gen(function* () {
726753 const statOption = ( target : string ) =>
727754 fileSystem . stat ( target ) . pipe ( Effect . asSome , Effect . orElseSucceed ( Option . none ) ) ;
728755
756+ /**
757+ * Builds a transcript identity snapshot, filling `inodeRaw` from the safe
758+ * numeric inode when available and from a raw bigint stat otherwise, so
759+ * large NTFS file IDs survive on Windows without extra I/O on other systems.
760+ */
729761 const transcriptIdentityEffect = Effect . fn ( "AgentSessionScanner.transcriptIdentity" ) ( function * (
730762 filePath : string ,
731763 stats : FileSystem . File . Info ,
0 commit comments