t3code-session-manager 0.0.0-stage → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/.claude-plugin/marketplace.json +21 -0
  2. package/.claude-plugin/plugin.json +19 -0
  3. package/CHANGELOG.md +149 -0
  4. package/LICENSE +21 -0
  5. package/README.md +661 -2
  6. package/README.pt.md +617 -0
  7. package/bin/entry.d.mts +2 -0
  8. package/bin/entry.mjs +19 -0
  9. package/bin/t3sm.mjs +44 -0
  10. package/commands/import.md +30 -0
  11. package/commands/organize.md +36 -0
  12. package/commands/status.md +24 -0
  13. package/commands/sync.md +26 -0
  14. package/dist/apply/apply.js +993 -0
  15. package/dist/apply/claudeWriter.js +168 -0
  16. package/dist/apply/copyTranscript.js +116 -0
  17. package/dist/apply/importer.js +697 -0
  18. package/dist/apply/materialize.js +335 -0
  19. package/dist/apply/waves.js +108 -0
  20. package/dist/assistant/core.js +295 -0
  21. package/dist/assistant/deps.js +256 -0
  22. package/dist/assistant/i18n.js +38 -0
  23. package/dist/assistant/messages.en.js +494 -0
  24. package/dist/assistant/messages.pt.js +495 -0
  25. package/dist/assistant/runner.js +64 -0
  26. package/dist/assistant/steps.js +1362 -0
  27. package/dist/build.json +1 -0
  28. package/dist/cli/applyScreen.js +158 -0
  29. package/dist/cli/commands/accounts.js +254 -0
  30. package/dist/cli/commands/apply.js +199 -0
  31. package/dist/cli/commands/changelog.js +61 -0
  32. package/dist/cli/commands/doctor.js +105 -0
  33. package/dist/cli/commands/help.js +158 -0
  34. package/dist/cli/commands/merge.js +224 -0
  35. package/dist/cli/commands/organize.js +872 -0
  36. package/dist/cli/commands/plan.js +161 -0
  37. package/dist/cli/commands/projects.js +430 -0
  38. package/dist/cli/commands/quarantine.js +203 -0
  39. package/dist/cli/commands/recover.js +230 -0
  40. package/dist/cli/commands/rollback.js +281 -0
  41. package/dist/cli/commands/scan.js +117 -0
  42. package/dist/cli/commands/schedule.js +288 -0
  43. package/dist/cli/commands/start.js +45 -0
  44. package/dist/cli/commands/status.js +615 -0
  45. package/dist/cli/commands/sync.js +336 -0
  46. package/dist/cli/commands/update.js +398 -0
  47. package/dist/cli/errors.js +53 -0
  48. package/dist/cli/failures.js +91 -0
  49. package/dist/cli/flags.js +53 -0
  50. package/dist/cli/help.en.js +549 -0
  51. package/dist/cli/help.pt.js +566 -0
  52. package/dist/cli/helpText.js +211 -0
  53. package/dist/cli/helpTopics.js +58 -0
  54. package/dist/cli/locked.js +12 -0
  55. package/dist/cli/main.js +155 -0
  56. package/dist/cli/screen.js +3 -0
  57. package/dist/cli/ui.js +111 -0
  58. package/dist/cli/words.js +2 -0
  59. package/dist/core/activity.js +16 -0
  60. package/dist/core/changelog.js +47 -0
  61. package/dist/core/config.js +530 -0
  62. package/dist/core/fsutil.js +171 -0
  63. package/dist/core/glob.js +34 -0
  64. package/dist/core/history.js +32 -0
  65. package/dist/core/journal.js +274 -0
  66. package/dist/core/lock.js +337 -0
  67. package/dist/core/mask.js +31 -0
  68. package/dist/core/paths.js +68 -0
  69. package/dist/core/pid.js +101 -0
  70. package/dist/core/run.js +4 -0
  71. package/dist/core/semver.js +18 -0
  72. package/dist/core/sysroot.js +29 -0
  73. package/dist/core/types.js +229 -0
  74. package/dist/core/uuid.js +29 -0
  75. package/dist/core/version.js +72 -0
  76. package/dist/help/convert.md +20 -0
  77. package/dist/help/convert.pt.md +21 -0
  78. package/dist/help/cwd-unreadable.md +22 -0
  79. package/dist/help/cwd-unreadable.pt.md +22 -0
  80. package/dist/help/decisions.md +20 -0
  81. package/dist/help/decisions.pt.md +20 -0
  82. package/dist/help/errors.md +20 -0
  83. package/dist/help/errors.pt.md +22 -0
  84. package/dist/help/held.md +20 -0
  85. package/dist/help/held.pt.md +20 -0
  86. package/dist/help/history.md +27 -0
  87. package/dist/help/history.pt.md +29 -0
  88. package/dist/help/instance-unavailable.md +18 -0
  89. package/dist/help/instance-unavailable.pt.md +19 -0
  90. package/dist/help/not-imported.md +19 -0
  91. package/dist/help/not-imported.pt.md +19 -0
  92. package/dist/help/orphaned.md +19 -0
  93. package/dist/help/orphaned.pt.md +19 -0
  94. package/dist/help/project-mismatch.md +15 -0
  95. package/dist/help/project-mismatch.pt.md +15 -0
  96. package/dist/help/t3-native.md +22 -0
  97. package/dist/help/t3-native.pt.md +22 -0
  98. package/dist/help/updates.md +26 -0
  99. package/dist/help/updates.pt.md +28 -0
  100. package/dist/help/watcher.md +24 -0
  101. package/dist/help/watcher.pt.md +25 -0
  102. package/dist/i18n/cli.js +41 -0
  103. package/dist/i18n/lang.js +55 -0
  104. package/dist/i18n/messages.en.js +1140 -0
  105. package/dist/i18n/messages.pt.js +1149 -0
  106. package/dist/i18n/words.js +12 -0
  107. package/dist/ops/accounts.js +170 -0
  108. package/dist/ops/autoUpdate.js +223 -0
  109. package/dist/ops/discoverAccounts.js +343 -0
  110. package/dist/ops/doctor.js +811 -0
  111. package/dist/ops/elevated.js +47 -0
  112. package/dist/ops/errorCodes.js +39 -0
  113. package/dist/ops/follow.js +558 -0
  114. package/dist/ops/merge.js +830 -0
  115. package/dist/ops/notify.js +249 -0
  116. package/dist/ops/plugin.js +92 -0
  117. package/dist/ops/projects.js +113 -0
  118. package/dist/ops/quarantine.js +415 -0
  119. package/dist/ops/rollback.js +868 -0
  120. package/dist/ops/schedule.js +464 -0
  121. package/dist/ops/successor.js +51 -0
  122. package/dist/ops/sync.js +859 -0
  123. package/dist/ops/syncStatus.js +290 -0
  124. package/dist/ops/update.js +273 -0
  125. package/dist/ops/updater.js +641 -0
  126. package/dist/ops/watch.js +676 -0
  127. package/dist/ops/watcherControl.js +212 -0
  128. package/dist/ops/watcherHealth.js +75 -0
  129. package/dist/organize/apply.js +495 -0
  130. package/dist/organize/history.js +192 -0
  131. package/dist/organize/plan.js +283 -0
  132. package/dist/organize/rename.js +58 -0
  133. package/dist/organize/sessions.js +100 -0
  134. package/dist/organize/titles.js +70 -0
  135. package/dist/organize/types.js +73 -0
  136. package/dist/plan/categories.js +104 -0
  137. package/dist/plan/dedupe.js +137 -0
  138. package/dist/plan/folders.js +82 -0
  139. package/dist/plan/names.js +93 -0
  140. package/dist/plan/ownership.js +316 -0
  141. package/dist/plan/planner.js +669 -0
  142. package/dist/plan/rehome.js +101 -0
  143. package/dist/plan/report.js +407 -0
  144. package/dist/sources/cache.js +89 -0
  145. package/dist/sources/claude.js +297 -0
  146. package/dist/sources/codex.js +496 -0
  147. package/dist/sources/flatten.js +23 -0
  148. package/dist/sources/jsonl.js +169 -0
  149. package/dist/sources/native.js +233 -0
  150. package/dist/sources/opencode.js +483 -0
  151. package/dist/sources/pi.js +133 -0
  152. package/dist/sources/registry.js +67 -0
  153. package/dist/sources/types.js +80 -0
  154. package/dist/t3/api.js +492 -0
  155. package/dist/t3/auth.js +248 -0
  156. package/dist/t3/compat.js +62 -0
  157. package/dist/t3/decode.js +408 -0
  158. package/dist/t3/errors.js +185 -0
  159. package/dist/t3/rpc.js +185 -0
  160. package/dist/t3/runtime.js +80 -0
  161. package/dist/ui/caps.js +56 -0
  162. package/dist/ui/components.js +202 -0
  163. package/dist/ui/layout.js +205 -0
  164. package/dist/ui/list.js +423 -0
  165. package/dist/ui/locale.js +73 -0
  166. package/dist/ui/organizePreview.js +72 -0
  167. package/dist/ui/progress.js +237 -0
  168. package/dist/ui/style.js +32 -0
  169. package/dist/ui/terminal.js +126 -0
  170. package/dist/ui/text.js +186 -0
  171. package/package.json +58 -4
  172. package/skills/t3code-sessions/SKILL.md +183 -0
@@ -0,0 +1,335 @@
1
+ // materializeConversions: write the Claude transcript of every convert-import item (OpenCode sessions, Codex compressed
2
+ // rollouts) into its account's projects folder, so T3 Code imports it like any other Claude transcript.
3
+ //
4
+ // Safety rules (global constraints): the only files t3sm writes outside its state dir are these converted transcripts,
5
+ // at exactly `<account home>/projects/<encodeClaudeProjectDir(root)>/<uuid>.jsonl`, and nothing there is ever
6
+ // overwritten unless t3sm itself wrote it and it is untouched since:
7
+ // - a NEW file is written to a temp name in the same folder, given its mtime, then published with link + unlink
8
+ // (publishNoClobber): if anything appeared at the target meanwhile, link fails with EEXIST and nothing is replaced
9
+ // (`target-exists`). Never rename-over for a new file.
10
+ // - a file t3sm wrote earlier (journaled `file-written`, sha256 unchanged) whose source has moved on is refreshed by
11
+ // rename-over, but only after re-hashing and re-stating it immediately before: changed since (resumed in T3 Code or
12
+ // the CLI) or modified within ACTIVE_WINDOW_MS -> left exactly as it is.
13
+ // - a file whose first record is not t3sm's provenance for this session is never ours, whatever the journal says.
14
+ // Each write is journaled BEFORE it is published (rollback deletes it while its sha256 still matches), and cancelled
15
+ // with `file-write-aborted` if it is not published after all (the journal never ends with a write that did not happen).
16
+ //
17
+ // mtime (writtenMtime): the written file gets the source session's last activity (as read now), but never a time in
18
+ // the future and never older than now - 20 days. Not "now": that would make it look in use (ACTIVE_WINDOW_MS) and hold
19
+ // its project. Not older than 20 days: Claude Code deletes transcripts by mtime after cleanupPeriodDays (default 30),
20
+ // so a converted file must never start inside that zone. The chosen time is journaled. It then goes through the
21
+ // importer's waves (bump -> scan -> import -> restore) like any other transcript.
22
+ //
23
+ // Deferrals (next run, not failures): the source was busy (SourceBusyError) or the session is in use
24
+ // (SessionActiveError) when read.
25
+ //
26
+ // Faithful copies (`copy: "faithful"`, spec §4.3): a Claude transcript from a folder T3 Code refuses, copied record by
27
+ // record by copyTranscript.faithfulCopy (no adapter: the transcript itself is read, never changed) and written,
28
+ // journaled and refreshed exactly like a conversion above. Differences: the source file is checked here (written within
29
+ // ACTIVE_WINDOW_MS -> deferred `active`; changed while read -> deferred `source-busy`); its activity is measured from
30
+ // the copy's text with discovery's own scanner (only cwd / sessionId differ), so the journaled `source` equals what
31
+ // discovery reports for the original until it grows; `file-written` also carries `rehomeOf` (the original as copied);
32
+ // and the copy is ours only if it still holds this source's provenance record (appended last, not first).
33
+
34
+ import { link, mkdir, open, rename, rm, unlink, utimes, writeFile } from "node:fs/promises";
35
+ import path from "node:path";
36
+ import { createHash } from "node:crypto";
37
+ import { setTimeout as delay } from "node:timers/promises";
38
+
39
+
40
+ import { effectiveWrites, near } from "../core/journal.js";
41
+ import { MoveRefused, RENAME_RETRIES, publishNoClobber, renameRefused, renameRetryDelay, sha256File, statSafe, sweepWriteTemps, writeTempPath, } from "../core/fsutil.js";
42
+ import { encodeClaudeProjectDir, expandHome, normalizeCwd, pathKey } from "../core/paths.js";
43
+ import { SessionActiveError, SourceBusyError, } from "../sources/types.js";
44
+ import { scanJsonl } from "../sources/jsonl.js";
45
+ import { isActive } from "../core/activity.js";
46
+ import { toClaudeJsonl } from "./claudeWriter.js";
47
+ import { PROVENANCE_TYPE, readFaithfulCopy, WRITTEN_BY } from "./copyTranscript.js";
48
+
49
+
50
+
51
+
52
+ /**
53
+ * Why an item was not materialized:
54
+ * - `no-reader`: no adapter with `read()` for its harness (the map holds every adapter that converts sessions), or a
55
+ * faithful copy of a session that is not a Claude transcript.
56
+ * - `target-outside-accounts`: the target is not `<account home>/projects/<encoded root>/<uuid>.jsonl`.
57
+ * - `target-exists`: a file t3sm did not write already sits at the target (or appeared there while writing).
58
+ * - `read-failed: <message>` / `write-failed: <message>`.
59
+ */
60
+
61
+
62
+
63
+ /** Not attempted this run, retried next run: the source kept changing, or the session is in use. */
64
+
65
+
66
+ /** A file t3sm writes (converted transcript, merge revision) is never given a time older than this before now. */
67
+ export const WRITTEN_MAX_AGE_MS = 20 * 86_400_000;
68
+
69
+ /** The mtime of a file t3sm writes: its session's last activity, clamped to [now - 20 days, now]. */
70
+ export function writtenMtime(activityMs , now ) {
71
+ const t = Number.isFinite(activityMs) ? Math.min(activityMs, now) : now;
72
+ return Math.max(t, now - WRITTEN_MAX_AGE_MS);
73
+ }
74
+
75
+
76
+
77
+
78
+
79
+
80
+
81
+
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+ /** Filesystem calls of the publish step; injected by tests to race it. */
92
+
93
+
94
+
95
+
96
+
97
+
98
+
99
+
100
+
101
+
102
+
103
+
104
+
105
+
106
+
107
+
108
+ const nodeFs = { link, unlink, rename };
109
+ const errText = (e ) => (e instanceof Error ? e.message : String(e));
110
+
111
+ /** The first line of a file (at most 64 KiB read), or null. */
112
+ async function firstLine(file ) {
113
+ try {
114
+ const fh = await open(file, "r");
115
+ try {
116
+ const buf = Buffer.alloc(65_536);
117
+ const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
118
+ const text = buf.subarray(0, bytesRead).toString("utf8");
119
+ const nl = text.indexOf("\n");
120
+ return nl < 0 ? null : text.slice(0, nl);
121
+ } finally {
122
+ await fh.close();
123
+ }
124
+ } catch {
125
+ return null;
126
+ }
127
+ }
128
+
129
+ export async function materializeConversions(
130
+ items ,
131
+ adapters ,
132
+ accounts ,
133
+ j ,
134
+ runId ,
135
+ opts = {},
136
+ ) {
137
+ const platform = opts.platform ?? process.platform;
138
+ const fs = opts.fs ?? nodeFs;
139
+ const now = opts.now ?? Date.now;
140
+ const p = platform === "win32" ? path.win32 : path.posix;
141
+ const key = (x ) => pathKey(x, platform);
142
+ const projectsDirs = new Set(accounts.map((a) => key(p.join(opts.home ? expandHome(a.home, opts.home) : a.home, "projects"))));
143
+
144
+ // The last file-written entry of every path: what t3sm itself put there.
145
+ const ours = new Map ();
146
+ // Aborted writes (never published) do not count: effectiveWrites drops them.
147
+ for (const e of effectiveWrites(await j.readAll(), key)) ours.set(key(e.path), e.sha256);
148
+
149
+ const swept = new Set ();
150
+ const res = { written: [], unchanged: [], resumed: [], failed: [], deferred: [], ready: [] };
151
+ for (const item of items) {
152
+ const a = item.action;
153
+ if (a.kind !== "convert-import") continue;
154
+ const s = item.session;
155
+ const fail = (reason ) => void res.failed.push({ item, reason });
156
+ const target = a.targetFile;
157
+ const parent = p.dirname(target);
158
+ const valid = !target.split(/[\\/]/).includes("..")
159
+ && p.basename(target) === `${a.uuid}.jsonl`
160
+ && p.basename(parent) === encodeClaudeProjectDir(normalizeCwd(a.projectRoot, platform))
161
+ && projectsDirs.has(key(p.dirname(parent)));
162
+ if (!valid) { fail("target-outside-accounts"); continue; }
163
+ const faithful = a.copy === "faithful";
164
+ const adapter = adapters.get(s.harness);
165
+ // A faithful copy needs no reader, but only a Claude transcript can be copied as it is.
166
+ if (faithful ? s.harness !== "claude" : !adapter?.read) { fail("no-reader"); continue; }
167
+
168
+ const cwd = platform === "win32" ? path.win32.normalize(a.projectRoot) : a.projectRoot;
169
+ let text ;
170
+ let activity ;
171
+ let rehomeOf ;
172
+ try {
173
+ if (faithful) {
174
+ const c = await readFaithful(s, { cwd, sessionId: a.uuid, fromCwd: s.cwd ?? a.rehomeFrom ?? "" }, now());
175
+ if ("defer" in c) { res.deferred.push({ item, reason: c.defer }); continue; }
176
+ ({ text, activity, rehomeOf } = c);
177
+ } else {
178
+ const t = await adapter .read (s);
179
+ activity = t.activity ?? { updatedAt: s.updatedAt, messageCount: s.messageCount };
180
+ text = toClaudeJsonl(t, { uuid: a.uuid, cwd }).text;
181
+ }
182
+ } catch (e) {
183
+ if (e instanceof SourceBusyError) res.deferred.push({ item, reason: "source-busy" });
184
+ else if (e instanceof SessionActiveError) res.deferred.push({ item, reason: "active" });
185
+ else fail(`read-failed: ${errText(e)}`);
186
+ continue;
187
+ }
188
+ const sha = createHash("sha256").update(text, "utf8").digest("hex");
189
+ const mtimeMs = writtenMtime(Date.parse(activity.updatedAt), now());
190
+ const provenance = text.slice(0, text.indexOf("\n"));
191
+ /**
192
+ * Ours = the journal says t3sm wrote it AND it still holds this session's provenance record: a conversion's is its
193
+ * first line; a faithful copy's is appended last (resumes append after it), so it is looked for in the whole file.
194
+ */
195
+ const isOurs = async () => ours.has(key(target))
196
+ && (faithful ? await holdsProvenance(target, s.nativeId) : (await firstLine(target)) === provenance);
197
+ const ready = () => readyItem(item, target, faithful ? null : text, res);
198
+
199
+ try {
200
+ const existing = await statSafe(target);
201
+ /** Refreshing our own earlier write: its sha256 at check time. */
202
+ let refreshFrom = null;
203
+ if (existing !== null) {
204
+ const have = await sha256File(target);
205
+ if (have === sha) {
206
+ // Identical. Ours with a fresh mtime = a crash between publish and utimes: give it its time back. Ours and
207
+ // aged past now - 20 days while waiting for its import: re-clamped, so it never drifts into Claude Code's
208
+ // cleanup zone (utimes only: same bytes, still the file the journal's file-written names).
209
+ const mine = ours.get(key(target)) === sha && !near(existing.mtimeMs, mtimeMs);
210
+ if (mine && (existing.mtimeMs > mtimeMs || existing.mtimeMs < now() - WRITTEN_MAX_AGE_MS)) await utimes(target, mtimeMs / 1000, mtimeMs / 1000);
211
+ res.unchanged.push(target);
212
+ await ready();
213
+ continue;
214
+ }
215
+ if (!(await isOurs())) { fail("target-exists"); continue; }
216
+ if (ours.get(key(target)) !== have || isActive(existing.mtimeMs, now())) {
217
+ // Written by t3sm, changed since (resumed) or being written now: it is the user's transcript now.
218
+ res.unchanged.push(target);
219
+ res.resumed.push(target);
220
+ await ready();
221
+ continue;
222
+ }
223
+ refreshFrom = have; // ours, untouched since, but the source has moved on
224
+ }
225
+ await mkdir(parent, { recursive: true });
226
+ if (!swept.has(key(parent))) { swept.add(key(parent)); await sweepWriteTemps(parent); } // left by a dead run
227
+ const tmp = writeTempPath(parent, a.uuid); // not *.jsonl: no scanner takes it
228
+ const before = ours.get(key(target));
229
+ let journaled = false;
230
+ let published = false;
231
+ try {
232
+ await writeFile(tmp, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
233
+ await utimes(tmp, mtimeMs / 1000, mtimeMs / 1000);
234
+ await j.append({
235
+ t: "file-written", runId, path: target, sha256: sha, mtimeMs,
236
+ source: { harness: s.harness, nativeId: s.nativeId, updatedAt: activity.updatedAt, messageCount: activity.messageCount },
237
+ ...(rehomeOf ? { rehomeOf } : {}),
238
+ });
239
+ journaled = true;
240
+ ours.set(key(target), sha);
241
+ await fs.beforePublish?.(target);
242
+ if (refreshFrom === null) {
243
+ try {
244
+ await publishNoClobber(tmp, target, fs);
245
+ published = true;
246
+ } catch (e) {
247
+ if (e instanceof MoveRefused && e.code === "EEXIST") { fail("target-exists"); continue; } // appeared meanwhile
248
+ throw e;
249
+ }
250
+ } else {
251
+ // Re-check right before replacing: still exactly the file we checked (our earlier write), and not in use.
252
+ // Windows refuses to rename over a file another process has open (an antivirus scan of the file just hashed):
253
+ // that refusal is retried like atomicWrite's (about 5 s), and the re-check runs again before every attempt.
254
+ let inUse = false;
255
+ for (let attempt = 0; ; attempt++) {
256
+ const st = await statSafe(target);
257
+ const still = st !== null && (await sha256File(target)) === refreshFrom;
258
+ if (st === null || !still || isActive(st.mtimeMs, now())) { inUse = true; break; }
259
+ try {
260
+ await fs.rename(tmp, target);
261
+ break;
262
+ } catch (e) {
263
+ if (!renameRefused(e) || attempt >= RENAME_RETRIES) throw e;
264
+ await (fs.sleep ?? delay)(renameRetryDelay(attempt));
265
+ }
266
+ }
267
+ if (inUse) {
268
+ res.unchanged.push(target);
269
+ res.resumed.push(target);
270
+ await ready();
271
+ continue;
272
+ }
273
+ published = true;
274
+ }
275
+ } finally {
276
+ if (journaled && !published) {
277
+ // The journal must not end with a write that never happened: cancel it, and forget it here too.
278
+ await j.append({ t: "file-write-aborted", runId, path: target });
279
+ if (before === undefined) ours.delete(key(target)); else ours.set(key(target), before);
280
+ }
281
+ await rm(tmp, { force: true }).catch(() => {});
282
+ }
283
+ res.written.push(target);
284
+ await ready();
285
+ } catch (e) {
286
+ fail(`write-failed: ${errText(e)}`);
287
+ }
288
+ }
289
+ return res;
290
+ }
291
+
292
+ /**
293
+ * The item as the importer sees it: its file is the written transcript. cwdOffsetBytes: a conversion's first record
294
+ * carries cwd (`text` given); a faithful copy's first cwd record is found in the file as it is now (`text` null).
295
+ */
296
+ async function readyItem(item , target , text , res ) {
297
+ const st = await statSafe(target);
298
+ if (st === null) throw new Error(`${target} vanished after it was written`);
299
+ const cwdOffsetBytes = text !== null ? Buffer.byteLength(text.slice(0, text.indexOf("\n") + 1), "utf8") : await cwdOffsetOf(target);
300
+ res.ready.push({ ...item, session: { ...item.session, file: st, cwdOffsetBytes } });
301
+ }
302
+
303
+ /** Bytes read up to and including the first record that carries cwd (the whole file when none does), as discovery counts. */
304
+ async function cwdOffsetOf(file ) {
305
+ let at = null;
306
+ const totals = await scanJsonl(file, {}, (o, info) => {
307
+ if (typeof o.cwd === "string" && o.cwd !== "") { at = info.offset; return "stop"; }
308
+ });
309
+ return at ?? totals.totalBytes;
310
+ }
311
+
312
+ /** Whether a file holds the provenance record of a faithful copy of session `nativeId`; false when it cannot be read. */
313
+ async function holdsProvenance(file , nativeId ) {
314
+ let found = false;
315
+ try {
316
+ await scanJsonl(file, {}, (o) => {
317
+ if (o.type === PROVENANCE_TYPE && o.writtenBy === WRITTEN_BY && o.fromSessionId === nativeId) { found = true; return "stop"; }
318
+ });
319
+ } catch {
320
+ return false;
321
+ }
322
+ return found;
323
+ }
324
+
325
+ /**
326
+ * The faithful copy of a Claude session, or why it waits (copyTranscript.readFaithfulCopy: written within
327
+ * ACTIVE_WINDOW_MS -> `active`; changed while it was read -> `source-busy`). Throws when the source cannot be read.
328
+ */
329
+ async function readFaithful(
330
+ s , o , now ,
331
+ ) {
332
+ const c = await readFaithfulCopy({ path: s.file.path, nativeId: s.nativeId }, o, now);
333
+ if ("defer" in c) return c;
334
+ return { text: c.text, activity: c.activity, rehomeOf: c.rehomeOf };
335
+ }
@@ -0,0 +1,108 @@
1
+ // Wave packing for the importer (docs/spikes/S2-import.md §5). Pure: no I/O.
2
+ //
3
+ // Every import item goes through a wave, oldest ORIGINAL mtime first across all projects. A wave is the next
4
+ // contiguous slice of that global order, so every item of a wave is at least as new as every item of earlier waves,
5
+ // and T3's thread updatedAt order (= bump time) ends up matching the original order.
6
+
7
+
8
+ import { pathKey } from "../core/paths.js";
9
+
10
+ /** 64 MiB per-source metadata budget in T3's scanner minus an 8 MiB margin (S2 §4/§5); the importer adds the wave's parked cost. */
11
+ export const WAVE_COST_CAP = 56 * 1024 * 1024;
12
+ /** Hard maximum of bumped files per project per wave (S2 §5). */
13
+ export const HARD_FILES_PER_PROJECT = 90;
14
+ /** Bump offsets are i ms below a base 2 s before now; more than 2000 files would reach "now" (future = ineligible). */
15
+ export const MAX_WAVE_FILES = 1000;
16
+ export const BUMP_LEAD_MS = 2000;
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+ /** A project root's identity (core pathKey). */
26
+ export function rootKey(root , platform = process.platform) {
27
+ return pathKey(root, platform);
28
+ }
29
+
30
+ export function itemRoot(i ) {
31
+ return i.action.kind === "skip" ? "" : i.action.projectRoot;
32
+ }
33
+
34
+ /** Ascending original mtime, then path: the global wave order. */
35
+ export function byOriginalMtime(a , b ) {
36
+ const d = a.session.file.mtimeMs - b.session.file.mtimeMs;
37
+ if (d !== 0) return d;
38
+ const pa = a.session.file.path, pb = b.session.file.path;
39
+ return pa < pb ? -1 : pa > pb ? 1 : 0;
40
+ }
41
+
42
+ /**
43
+ * Files of one project per wave: min(filesPerProject, 90), at least 1.
44
+ *
45
+ * S2 §5 derives the capacity as min(filesPerProject, 90, 100 - R), R = the project's not-yet-imported in-window
46
+ * transcripts outside the wave. T3 spends its 100-per-call cap in mtime-DESCENDING order, so only transcripts newer
47
+ * than the wave's bump base (now - 2 s) can take a slot ahead of the bumped files. With parking (every other
48
+ * not-imported, in-window transcript of the wave's projects is moved to now + 7 days for the wave, where T3 skips it;
49
+ * a project with one in use is held instead), what
50
+ * remains in the window is older than the bump base (active files are >= 2 s old in practice; skipped and
51
+ * already-imported transcripts are older still), so R = 0 here. The hard max 90 keeps 10 slots of slack for files
52
+ * written within the last 2 s.
53
+ */
54
+ export function projectCapacity(filesPerProject ) {
55
+ return Math.max(1, Math.min(filesPerProject, HARD_FILES_PER_PROJECT));
56
+ }
57
+
58
+ /** All items of a wave in ascending original mtime (the bump order). */
59
+ export function waveItems(w ) {
60
+ return w.projects.flatMap((p) => p.items).sort(byOriginalMtime);
61
+ }
62
+
63
+ /**
64
+ * Greedy packing of the global ascending order: a new wave starts when the next item would exceed projectsPerWave
65
+ * projects, its project's capacity, MAX_WAVE_FILES, or the cost cap. An item that alone exceeds the cost cap gets a
66
+ * wave of its own (T3 can still try it; it fails visibly instead of blocking the run). Deterministic.
67
+ */
68
+ export function buildWaves(items , batch , cost , opts = {}) {
69
+ const platform = opts.platform ?? process.platform;
70
+ const maxCost = opts.maxCost ?? WAVE_COST_CAP;
71
+ const sorted = [...items].sort(byOriginalMtime);
72
+ const waves = [];
73
+ let cur = null;
74
+ for (const it of sorted) {
75
+ const key = rootKey(itemRoot(it), platform);
76
+ const c = Math.max(0, cost(it));
77
+ const cap = projectCapacity(batch.filesPerProject);
78
+ const fits = cur !== null && (() => {
79
+ const p = cur.byKey.get(key);
80
+ if (!p && cur.byKey.size >= batch.projectsPerWave) return false;
81
+ if (p && p.items.length >= cap) return false;
82
+ if (cur.n >= MAX_WAVE_FILES) return false;
83
+ return cur.cost + c <= maxCost;
84
+ })();
85
+ if (!fits) {
86
+ cur = { wave: { projects: [] }, byKey: new Map(), cost: 0, n: 0 };
87
+ waves.push(cur.wave);
88
+ }
89
+ let p = cur .byKey.get(key);
90
+ if (!p) {
91
+ p = { projectRoot: itemRoot(it), items: [] };
92
+ cur .byKey.set(key, p);
93
+ cur .wave.projects.push(p);
94
+ }
95
+ p.items.push(it);
96
+ cur .cost += c;
97
+ cur .n++;
98
+ }
99
+ return waves;
100
+ }
101
+
102
+ /** Bump targets for n files: the i-th (ascending original mtime) gets (now - 2 s) + i ms. Throws unless every target is strictly before now. */
103
+ export function bumpTargets(n , now ) {
104
+ const base = Math.floor(now) - BUMP_LEAD_MS;
105
+ const out = Array.from({ length: n }, (_, i) => base + i);
106
+ if (n > 0 && out[n - 1] >= now) throw new Error(`bump target not strictly before now, would be in the future (${n} files in one wave); waves hold at most ${MAX_WAVE_FILES}`);
107
+ return out;
108
+ }