castle-web-cli 0.4.214 → 0.4.216

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.
package/dist/cloudGit.js CHANGED
@@ -1,8 +1,9 @@
1
- import { execFile } from 'child_process';
2
- import { randomUUID } from 'crypto';
1
+ import { execFile, spawn } from 'child_process';
2
+ import { createHash, randomUUID } from 'crypto';
3
3
  import * as fs from 'fs';
4
4
  import * as os from 'os';
5
5
  import * as path from 'path';
6
+ import { fileURLToPath } from 'url';
6
7
  import { GIT_HOSTS, GIT_REMOTE_NAME, isSandboxToken, runGit } from './gitRemote.js';
7
8
  import { COVER_FILE } from './localPaths.js';
8
9
  export const COMMIT_REASONS = ['turn', 'task', 'leave', 'manual', 'sync'];
@@ -29,6 +30,13 @@ export const EXIT_ERROR = 1;
29
30
  export const EXIT_NOT_ENABLED = 2;
30
31
  /** A merge with the remote is waiting on the agent; nothing was committed. */
31
32
  export const EXIT_CONFLICT = 3;
33
+ /**
34
+ * GIT_HISTORY_UNAVAILABLE: the deck's refs name commits whose objects are gone (a cold resume,
35
+ * whose checkpoint carries no `.git/objects`) and neither the Castle remote, the S3 mirror nor
36
+ * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
37
+ */
38
+ export const EXIT_HISTORY_UNAVAILABLE = 4;
39
+ export const HISTORY_UNAVAILABLE_CODE = 'GIT_HISTORY_UNAVAILABLE';
32
40
  export class CloudGitError extends Error {
33
41
  exitCode;
34
42
  constructor(message, exitCode = EXIT_ERROR) {
@@ -40,8 +48,9 @@ export class CloudGitError extends Error {
40
48
  // Castle's excludes, in .git/info/exclude rather than a .gitignore, so they apply whatever
41
49
  // the deck's own .gitignore says and never show up as a change to the deck.
42
50
  export const CLOUD_EXCLUDES = ['node_modules/', 'dist/', '/imports/', '.castle/', '.vite/'];
43
- // More loose objects than this and a commit packs the repo: loose objects count toward the
44
- // checkpoint's file cap, and `.git` rides in every draft checkpoint.
51
+ // More loose objects than this and a commit packs the repo. Draft checkpoints no longer carry
52
+ // `.git/objects` (history is rebuilt from the remote, the S3 mirror and the snapshot bundle on
53
+ // a cold resume), but a pile of loose objects still slows every git command and the bundle.
45
54
  export const LOOSE_OBJECT_LIMIT = 200;
46
55
  const PACK_TIMEOUT_MS = 90_000;
47
56
  // A command that has already run this long leaves packing to the next one, so a caller's
@@ -68,8 +77,13 @@ const PUSH_RETRIES = 2;
68
77
  export const CONFLICT_MARKER_FILE = path.join('.castle', 'agent', 'git-conflict.json');
69
78
  /** Written by `git attach` when it took the remote's version over a differing cloud copy. */
70
79
  export const ADOPTED_MARKER_FILE = path.join('.castle', 'agent', 'git-adopted.json');
80
+ /** Written when a rehydrate gave up local commits nobody had (see recoverLostHistory). */
81
+ export const HISTORY_RECOVERED_FILE = path.join('.castle', 'agent', 'git-history-recovered.json');
82
+ export const RECOVERED_COMMIT_MESSAGE = 'Edits restored after lost history';
83
+ /** Written with it, once: the notice and instruction the serve turns into an agent turn. */
84
+ export const HISTORY_LOST_MARKER_FILE = path.join('.castle', 'agent', 'git-history-lost.json');
71
85
  /** Every marker the serve turns into an agent turn. */
72
- export const AGENT_MARKER_FILES = [CONFLICT_MARKER_FILE, ADOPTED_MARKER_FILE];
86
+ export const AGENT_MARKER_FILES = [CONFLICT_MARKER_FILE, ADOPTED_MARKER_FILE, HISTORY_LOST_MARKER_FILE];
73
87
  /** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
74
88
  export const BUSY_FILE = path.join('.castle', 'agent', 'git-busy.json');
75
89
  /** The remote has (or may have) work that waits to be merged until the deck is idle. */
@@ -94,6 +108,7 @@ export const ATTACH_BACKUP_KEEP = 10;
94
108
  // sets it to just short of its SIGKILL). Every git step's own timeout is capped by what is left,
95
109
  // so no step is still running when the kill lands, and none starts without time to finish.
96
110
  export const DEADLINE_ENV = 'CASTLE_GIT_DEADLINE';
111
+ export const AGENT_ROLE_ENV = 'CASTLE_AGENT_ROLE';
97
112
  const MIN_STEP_MS = 2_000;
98
113
  const MAIN = 'main';
99
114
  const REMOTE_MAIN = `refs/remotes/${GIT_REMOTE_NAME}/${MAIN}`;
@@ -142,8 +157,9 @@ function cloudGitEnv(baseEnv) {
142
157
  export function cloudGitRunner(baseEnv = process.env) {
143
158
  const env = cloudGitEnv(baseEnv);
144
159
  return (args, cwd, opts) => runGit(args, cwd, {
145
- env: opts?.indexFile ? { ...env, GIT_INDEX_FILE: opts.indexFile } : env,
160
+ env: { ...env, ...(opts?.indexFile ? { GIT_INDEX_FILE: opts.indexFile } : {}), ...opts?.env },
146
161
  timeoutMs: opts?.timeoutMs,
162
+ input: opts?.input,
147
163
  });
148
164
  }
149
165
  // The async form, for the serve and the IDE server: their event loop must never wait on git.
@@ -166,7 +182,57 @@ function runGitAsync(args, cwd, baseEnv) {
166
182
  });
167
183
  });
168
184
  }
169
- export function defaultCloudGitDeps(whoAmI) {
185
+ // A bundle URL is a presigned S3 GET: https only (plain http is allowed to this machine alone,
186
+ // which is what the tests serve from).
187
+ function allowedBundleUrl(url) {
188
+ try {
189
+ const parsed = new URL(url);
190
+ if (parsed.protocol === 'https:')
191
+ return true;
192
+ return parsed.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(parsed.hostname);
193
+ }
194
+ catch {
195
+ return false;
196
+ }
197
+ }
198
+ /**
199
+ * Downloads `url` to `dest`, checking its exact size and SHA-256 where the mirror recorded them
200
+ * (a bundle listed by an older mirror run has neither); removes `dest` on any failure.
201
+ */
202
+ // A bundle listed without its size (an older mirror run) is still bounded.
203
+ export const UNSIZED_DOWNLOAD_MAX_BYTES = 2 * 1024 * 1024 * 1024;
204
+ export async function downloadVerified(url, dest, opts) {
205
+ if (!allowedBundleUrl(url))
206
+ throw new Error('refusing a bundle URL that is not https');
207
+ const limit = opts.bytes ?? UNSIZED_DOWNLOAD_MAX_BYTES;
208
+ const handle = await fs.promises.open(dest, 'w');
209
+ try {
210
+ const res = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs) });
211
+ if (!res.ok || !res.body)
212
+ throw new Error(`download failed: HTTP ${res.status}`);
213
+ const hash = createHash('sha256');
214
+ let size = 0;
215
+ for await (const chunk of res.body) {
216
+ size += chunk.byteLength;
217
+ if (size > limit)
218
+ throw new Error(`download is larger than the ${limit} bytes allowed`);
219
+ hash.update(chunk);
220
+ await handle.write(chunk);
221
+ }
222
+ if (opts.bytes !== null && size !== opts.bytes)
223
+ throw new Error(`download is ${size} bytes, expected ${opts.bytes}`);
224
+ const digest = hash.digest('hex');
225
+ if (opts.sha256 !== null && digest !== opts.sha256.toLowerCase())
226
+ throw new Error('download does not match its sha256');
227
+ }
228
+ catch (e) {
229
+ await handle.close().catch(() => undefined);
230
+ fs.rmSync(dest, { force: true });
231
+ throw e;
232
+ }
233
+ await handle.close();
234
+ }
235
+ export function defaultCloudGitDeps(whoAmI, extra = {}) {
170
236
  // A caller's time limit arrives as SIGTERM: the command stops at its next safe point (never
171
237
  // inside a git command) instead of dying wherever it happens to be.
172
238
  let stopping = false;
@@ -185,6 +251,8 @@ export function defaultCloudGitDeps(whoAmI) {
185
251
  hostname: () => os.hostname(),
186
252
  isAlive: pidIsAlive,
187
253
  stopRequested: () => new Promise((resolve) => setImmediate(() => resolve(stopping))),
254
+ download: downloadVerified,
255
+ ...extra,
188
256
  };
189
257
  }
190
258
  // A git step's timeout: its own, capped by the time left before the caller's deadline. A step
@@ -234,9 +302,38 @@ function localConfig(ctx, key) {
234
302
  function gitDir(dir) {
235
303
  return path.join(dir, '.git');
236
304
  }
305
+ // A deck restored from a draft checkpoint has its `.git` without `.git/objects`: the capture
306
+ // leaves that directory out and stores files only, so every empty directory is gone too. Git
307
+ // does not even take such a directory for a repo ("not a git repository"). This puts back the
308
+ // empty directories git requires -- nothing else; the objects themselves are rehydrated under
309
+ // the deck lock (`castle-web git rehydrate`). Only for a real `.git` directory with a HEAD file.
310
+ export function repairGitSkeleton(dir) {
311
+ const root = gitDir(dir);
312
+ try {
313
+ if (!fs.lstatSync(root).isDirectory() || !fs.lstatSync(path.join(root, 'HEAD')).isFile())
314
+ return;
315
+ }
316
+ catch {
317
+ return;
318
+ }
319
+ for (const sub of [['objects', 'info'], ['objects', 'pack'], ['refs', 'heads'], ['refs', 'tags']]) {
320
+ const full = path.join(root, ...sub);
321
+ try {
322
+ if (!fs.existsSync(full))
323
+ fs.mkdirSync(full, { recursive: true, mode: 0o755 });
324
+ }
325
+ catch {
326
+ /* best effort: git reports what is still wrong */
327
+ }
328
+ }
329
+ }
237
330
  export function mergeInProgress(dir) {
238
331
  return fs.existsSync(path.join(gitDir(dir), 'MERGE_HEAD'));
239
332
  }
333
+ /** A merge (or a recovered one's conflict markers) waits on the agent: only `--resolve` commits. */
334
+ export function mergeWaiting(dir) {
335
+ return mergeInProgress(dir) || readMergeState(dir)?.recovered === true;
336
+ }
240
337
  function lines(text) {
241
338
  return text.split('\n').map((l) => l.trim()).filter(Boolean);
242
339
  }
@@ -262,6 +359,7 @@ export function isAttached(dir, git = cloudGitRunner()) {
262
359
  catch {
263
360
  return false;
264
361
  }
362
+ repairGitSkeleton(dir);
265
363
  const result = git(['config', '--local', '--get', 'castle.cloud'], dir);
266
364
  return result.status === 0 && result.stdout.trim() === 'true';
267
365
  }
@@ -283,6 +381,7 @@ export async function cloudGitModeAsync(dir, env = process.env) {
283
381
  catch {
284
382
  return false;
285
383
  }
384
+ repairGitSkeleton(dir);
286
385
  const result = await runGitAsync(['config', '--local', '--get', 'castle.cloud'], dir, env);
287
386
  return result.status === 0 && result.stdout.trim() === 'true';
288
387
  }
@@ -315,11 +414,27 @@ export function deckBusy(ctx) {
315
414
  return false;
316
415
  }
317
416
  }
417
+ export function deckTasksBusy(ctx) {
418
+ if (!deckBusy(ctx))
419
+ return false;
420
+ try {
421
+ const held = JSON.parse(fs.readFileSync(path.join(ctx.dir, BUSY_FILE), 'utf-8'));
422
+ return held.tasks !== false;
423
+ }
424
+ catch {
425
+ return false;
426
+ }
427
+ }
318
428
  /** The serve's side of deckBusy. */
319
- export function setDeckBusy(dir, busy) {
429
+ export function setDeckBusy(dir, busy, opts) {
320
430
  const file = path.join(dir, BUSY_FILE);
321
431
  if (busy) {
322
- writeJsonAtomic(file, { pid: process.pid, host: os.hostname(), start: processStartTime(process.pid) });
432
+ writeJsonAtomic(file, {
433
+ pid: process.pid,
434
+ host: os.hostname(),
435
+ start: processStartTime(process.pid),
436
+ tasks: opts?.tasks ?? true,
437
+ });
323
438
  return;
324
439
  }
325
440
  try {
@@ -565,7 +680,8 @@ export function safeAuthorName(username) {
565
680
  // a placeholder rather than failing, and the next one asks again. The value goes after the
566
681
  // key, where git config takes it literally whatever it starts with.
567
682
  async function identityArgs(ctx) {
568
- if (localConfig(ctx, 'user.email') && localConfig(ctx, 'user.name'))
683
+ const set = run(ctx, ['config', '--local', '--get-regexp', '^user\\.(name|email)$']);
684
+ if (set.status === 0 && lines(set.stdout).length >= 2)
569
685
  return [];
570
686
  let user = null;
571
687
  try {
@@ -764,14 +880,17 @@ function commitMessageArgs(opts, reason) {
764
880
  args.push('--trailer', AGENT_TRAILER);
765
881
  return args;
766
882
  }
767
- function looseObjectCount(ctx) {
768
- const match = /^count: (\d+)$/m.exec(must(ctx, ['count-objects', '-v']));
769
- return match ? Number(match[1]) : 0;
883
+ // Fetches land as packs (unpackLimit=1), so packs pile up as loose objects used to.
884
+ const PACK_COUNT_LIMIT = 30;
885
+ function objectCounts(ctx) {
886
+ const out = must(ctx, ['count-objects', '-v']);
887
+ return { loose: Number(/^count: (\d+)$/m.exec(out)?.[1] ?? 0), packs: Number(/^packs: (\d+)$/m.exec(out)?.[1] ?? 0) };
770
888
  }
771
889
  // Geometric repacking rolls the loose objects into a new pack and merges only small packs,
772
890
  // so it stays cheap as history grows (unlike rewriting one big pack every time).
773
891
  export function packIfNeeded(ctx) {
774
- if (looseObjectCount(ctx) <= LOOSE_OBJECT_LIMIT)
892
+ const counts = objectCounts(ctx);
893
+ if (counts.loose <= LOOSE_OBJECT_LIMIT && counts.packs <= PACK_COUNT_LIMIT)
775
894
  return false;
776
895
  const geometric = run(ctx, ['repack', '-d', '-q', '--geometric=2'], { timeoutMs: PACK_TIMEOUT_MS });
777
896
  if (geometric.status !== 0)
@@ -793,6 +912,1138 @@ async function packAfterCommit(ctx, reason) {
793
912
  ctx.deps.warn(`Packing the repo failed (the commit is fine): ${e instanceof Error ? e.message : String(e)}`);
794
913
  }
795
914
  }
915
+ // --- snapshot bundle and rehydrate ------------------------------------------
916
+ //
917
+ // castle-sandboxes docs/git-remotes-snapshot-without-history.md, sections 2 and 3. Draft
918
+ // checkpoints no longer carry `.git/objects`. History lives on the Castle remote (code.storage)
919
+ // and in the deck's S3 mirror; what neither is known to hold yet -- local commits, and pushed
920
+ // ones the mirror has not caught up with -- goes in `.git/castle-snapshot.bundle`, which a
921
+ // checkpoint does carry. A cold resume rebuilds the objects with `castle-web git rehydrate`,
922
+ // which attach, sync and commits start in the background (exiting GIT_HISTORY_UNAVAILABLE at
923
+ // once: the host's checkpoint keeps the files whatever git does); the leave commit never does.
924
+ // Nothing here touches the working tree.
925
+ /** Every object the deck's local state reaches that the S3 mirror is not known to have. */
926
+ export const SNAPSHOT_BUNDLE_FILE = path.join('.git', 'castle-snapshot.bundle');
927
+ // What the snapshot was written from (so an unchanged one is not rewritten every turn), and
928
+ // the tips left out of it for being too big.
929
+ export const SNAPSHOT_KEY_FILE = path.join('.git', 'castle-snapshot.json');
930
+ /** main as ghost last reported the deck's S3 mirror had it: the bundle's floor. Only moves forward. */
931
+ export const MIRRORED_REF = 'refs/castle/mirrored';
932
+ /**
933
+ * One rehydrate at a time. Not named `*.lock`: clearStaleGitLocks removes those at the top of
934
+ * .git after a minute, and a rehydrate runs far longer than that.
935
+ */
936
+ export const REHYDRATE_LOCK_FILE = path.join('.git', 'castle-rehydrate-lock');
937
+ /** Failed rehydrates and when the next background one may start (exponential backoff). */
938
+ export const REHYDRATE_STATE_FILE = path.join('.git', 'castle-rehydrate-state.json');
939
+ /** Where a background rehydrate writes its output. */
940
+ export const REHYDRATE_LOG_FILE = path.join('.castle', 'agent', 'git-rehydrate.log');
941
+ /** `off` stops commands from starting a background rehydrate (tests). */
942
+ export const BACKGROUND_REHYDRATE_ENV = 'CASTLE_GIT_BACKGROUND_REHYDRATE';
943
+ // The host's capture refuses any file over 32 MiB and fails the whole checkpoint with it. The
944
+ // snapshot and one set-aside lost snapshot stay under 48 MiB together.
945
+ export const SNAPSHOT_CAP_BYTES = 24 * 1024 * 1024;
946
+ /** A smaller cap, for tests. */
947
+ export const SNAPSHOT_CAP_ENV = 'CASTLE_GIT_SNAPSHOT_CAP_BYTES';
948
+ // Older builds split big snapshots into parts; whatever they left is removed.
949
+ const OLD_PART_FILE_RE = /^castle-snapshot-\d+\.bundle$/;
950
+ const OLD_PART_REF_PREFIX = 'refs/castle-snapshot-parts/';
951
+ const LOST_BUNDLE_RE = /^castle-lost-\d+-\d+\.bundle$/;
952
+ const SCRATCH_PREFIX = 'castle-rehydrate-';
953
+ const REHYDRATE_BUDGET_MS = 15 * 60_000;
954
+ const REHYDRATE_STEP_MS = 10 * 60_000;
955
+ const BACKOFF_MIN_MS = 60_000;
956
+ const BACKOFF_MAX_MS = 30 * 60_000;
957
+ const MIRROR_STATE_TIMEOUT_MS = 3_000;
958
+ const MIRROR_BUNDLES_TIMEOUT_MS = 15_000;
959
+ const CONNECTIVITY_TIMEOUT_MS = 120_000;
960
+ const BUNDLE_TIMEOUT_MS = 30_000;
961
+ // The host bounds the whole leave commit at 10 seconds.
962
+ const LEAVE_BUNDLE_TIMEOUT_MS = 4_000;
963
+ const REHYDRATE_LOG_MAX_BYTES = 256 * 1024;
964
+ const FREE_SPACE_MARGIN_BYTES = 256 * 1024 * 1024;
965
+ const OBJECT_ID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
966
+ // Every command in the scratch repo: its gc must never judge the deck's objects (it sees none of
967
+ // the deck's refs), and a fetch lands as one pack, so a killed one leaves nothing half-there.
968
+ const SCRATCH_CONFIG = [
969
+ '-c', 'gc.auto=0',
970
+ '-c', 'maintenance.auto=false',
971
+ '-c', 'fetch.unpackLimit=1',
972
+ '-c', 'transfer.unpackLimit=1',
973
+ '-c', 'core.createObject=rename',
974
+ ];
975
+ function withTimeout(promise, ms, what) {
976
+ let timer;
977
+ const timeout = new Promise((_, reject) => {
978
+ timer = setTimeout(() => reject(new Error(`${what} timed out`)), ms);
979
+ timer.unref();
980
+ });
981
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
982
+ }
983
+ function errorText(e) {
984
+ return e instanceof Error ? e.message : String(e);
985
+ }
986
+ // A ref's value without looking at the object: `revParse` peels to a commit, which fails when
987
+ // the commit's object is missing -- exactly the state this section has to see through.
988
+ function refValue(ctx, ref) {
989
+ const result = run(ctx, ['rev-parse', '--verify', '--quiet', ref]);
990
+ const sha = result.status === 0 ? result.stdout.trim() : '';
991
+ return OBJECT_ID_RE.test(sha) ? sha : null;
992
+ }
993
+ function remoteDeckId(ctx) {
994
+ const url = configuredRemoteUrl(ctx);
995
+ return (url ? CASTLE_REMOTE_RE.exec(url)?.[2] : undefined) ?? null;
996
+ }
997
+ function deckIdFor(ctx) {
998
+ return remoteDeckId(ctx) ?? readDeckId(ctx.dir);
999
+ }
1000
+ function snapshotCap(ctx) {
1001
+ const override = Number(ctx.deps.env[SNAPSHOT_CAP_ENV]);
1002
+ return Number.isInteger(override) && override > 0 ? override : SNAPSHOT_CAP_BYTES;
1003
+ }
1004
+ function fileSize(file) {
1005
+ try {
1006
+ return fs.statSync(file).size;
1007
+ }
1008
+ catch {
1009
+ return 0;
1010
+ }
1011
+ }
1012
+ // Castle's own refs and remote-tracking ones are not the deck's local state.
1013
+ function isCastleRef(name) {
1014
+ return name.startsWith('refs/castle/') || name.startsWith('refs/castle-') || name.startsWith('refs/remotes/');
1015
+ }
1016
+ // A local branch, HEAD or MERGE_HEAD: the tips a rehydrate must bring back or deliberately give
1017
+ // up. Every other ref (tags, stash, remote-tracking, Castle's own) can simply go when its
1018
+ // object is gone.
1019
+ function isBranchTip(name) {
1020
+ return name === 'HEAD' || name === 'MERGE_HEAD' || name.startsWith('refs/heads/');
1021
+ }
1022
+ function allRefs(ctx) {
1023
+ const args = ['for-each-ref', '--format=%(objectname) %(refname)'];
1024
+ const listed = run(ctx, args);
1025
+ if (listed.status !== 0)
1026
+ throw new CloudGitError(describeFailure(args, listed));
1027
+ const out = [];
1028
+ for (const line of lines(listed.stdout)) {
1029
+ const space = line.indexOf(' ');
1030
+ const sha = line.slice(0, space);
1031
+ const name = line.slice(space + 1);
1032
+ if (OBJECT_ID_RE.test(sha) && name)
1033
+ out.push({ name, sha });
1034
+ }
1035
+ return out;
1036
+ }
1037
+ function readShaFile(file) {
1038
+ try {
1039
+ const sha = fs.readFileSync(file, 'utf-8').split('\n')[0].trim();
1040
+ return OBJECT_ID_RE.test(sha) ? sha : null;
1041
+ }
1042
+ catch {
1043
+ return null;
1044
+ }
1045
+ }
1046
+ function readRefState(ctx) {
1047
+ const refs = allRefs(ctx);
1048
+ const root = gitDir(ctx.dir);
1049
+ let head = null;
1050
+ try {
1051
+ const text = fs.readFileSync(path.join(root, 'HEAD'), 'utf-8').trim();
1052
+ if (text.startsWith('ref: ')) {
1053
+ const target = text.slice('ref: '.length).trim();
1054
+ head = refs.find((ref) => ref.name === target)?.sha ?? null;
1055
+ }
1056
+ else if (OBJECT_ID_RE.test(text)) {
1057
+ head = text;
1058
+ }
1059
+ }
1060
+ catch {
1061
+ head = null;
1062
+ }
1063
+ return { refs, head, mergeHead: readShaFile(path.join(root, 'MERGE_HEAD')), origHead: readShaFile(path.join(root, 'ORIG_HEAD')) };
1064
+ }
1065
+ function stateRef(state, name) {
1066
+ return state.refs.find((ref) => ref.name === name)?.sha ?? null;
1067
+ }
1068
+ /** The deck's local state: HEAD, MERGE_HEAD, ORIG_HEAD and every ref but Castle's and remote ones. */
1069
+ function localTips(state) {
1070
+ const tips = [];
1071
+ if (state.head)
1072
+ tips.push({ name: 'HEAD', sha: state.head });
1073
+ if (state.mergeHead)
1074
+ tips.push({ name: 'MERGE_HEAD', sha: state.mergeHead });
1075
+ if (state.origHead)
1076
+ tips.push({ name: 'ORIG_HEAD', sha: state.origHead });
1077
+ return [...tips, ...state.refs.filter((tip) => !isCastleRef(tip.name))];
1078
+ }
1079
+ /** The tips whose history the deck needs: its local state (ORIG_HEAD aside) and castle/main. */
1080
+ function requiredTips(state) {
1081
+ const tips = localTips(state).filter((tip) => tip.name !== 'ORIG_HEAD');
1082
+ const remote = stateRef(state, REMOTE_MAIN);
1083
+ if (remote)
1084
+ tips.push({ name: REMOTE_MAIN, sha: remote });
1085
+ return tips;
1086
+ }
1087
+ /**
1088
+ * The tips whose object is not in the object store -- one `cat-file` for all of them. A
1089
+ * branch-like tip must be a commit; a tag may name any object, so only its existence counts.
1090
+ * An error other than a missing object throws.
1091
+ */
1092
+ function missingTips(ctx, tips) {
1093
+ if (tips.length === 0)
1094
+ return [];
1095
+ const args = ['cat-file', '--batch-check=%(objectname)'];
1096
+ const input = tips.map((tip) => (isBranchTip(tip.name) || tip.name === REMOTE_MAIN ? `${tip.sha}^{commit}` : tip.sha));
1097
+ const result = run(ctx, args, { input: input.join('\n') + '\n' });
1098
+ if (result.status !== 0)
1099
+ throw new CloudGitError(describeFailure(args, result));
1100
+ const out = result.stdout.split('\n');
1101
+ return tips.filter((_, i) => {
1102
+ const line = (out[i] ?? '').trim();
1103
+ if (OBJECT_ID_RE.test(line))
1104
+ return false;
1105
+ if (/ missing$/.test(line))
1106
+ return true;
1107
+ throw new CloudGitError(`Could not check the deck's git objects: unexpected \`git cat-file\` output ${JSON.stringify(line)}`);
1108
+ });
1109
+ }
1110
+ function historyMissing(ctx, state = readRefState(ctx)) {
1111
+ return missingTips(ctx, requiredTips(state));
1112
+ }
1113
+ /** Whether the deck's history is being rebuilt: refs name objects that are not here. */
1114
+ export function historyLoading(dir, git = cloudGitRunner()) {
1115
+ try {
1116
+ repairGitSkeleton(dir);
1117
+ const ctx = { dir, deps: { git }, startedAt: 0 };
1118
+ return historyMissing(ctx).length > 0;
1119
+ }
1120
+ catch {
1121
+ return false;
1122
+ }
1123
+ }
1124
+ // The full test, after a rehydrate: every object reachable from the tips is here. The object
1125
+ // list is streamed, never held. Git 2.39 (the sandbox image's) exits with "Could not read" /
1126
+ // "Failed to traverse parents" on a missing commit where newer ones print `?<id>`; both mean
1127
+ // incomplete. Any other failure throws.
1128
+ async function historyIncomplete(ctx, shas) {
1129
+ const wanted = [...new Set(shas)];
1130
+ if (wanted.length === 0)
1131
+ return false;
1132
+ const args = ['rev-list', '--objects', '--no-object-names', '--missing=print', ...wanted];
1133
+ const timeoutMs = stepTimeout(ctx, args.slice(0, 4), CONNECTIVITY_TIMEOUT_MS) ?? CONNECTIVITY_TIMEOUT_MS;
1134
+ return new Promise((resolve, reject) => {
1135
+ const child = spawn('git', args, {
1136
+ cwd: ctx.dir,
1137
+ env: { ...cloudGitEnv(ctx.deps.env), LC_ALL: 'C', LANGUAGE: 'C' },
1138
+ stdio: ['ignore', 'pipe', 'pipe'],
1139
+ });
1140
+ let missing = false;
1141
+ let tail = '';
1142
+ let stderr = '';
1143
+ child.stdout.setEncoding('utf-8');
1144
+ child.stdout.on('data', (chunk) => {
1145
+ const text = tail + chunk;
1146
+ if (/(?:^|\n)\?/.test(text))
1147
+ missing = true;
1148
+ tail = text.slice(text.lastIndexOf('\n') + 1);
1149
+ });
1150
+ child.stderr.setEncoding('utf-8');
1151
+ child.stderr.on('data', (chunk) => {
1152
+ stderr = (stderr + chunk).slice(-4000);
1153
+ });
1154
+ const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
1155
+ child.on('error', (e) => {
1156
+ clearTimeout(timer);
1157
+ reject(e);
1158
+ });
1159
+ child.on('close', (code, signal) => {
1160
+ clearTimeout(timer);
1161
+ if (tail.startsWith('?'))
1162
+ missing = true;
1163
+ if (code === 0)
1164
+ return resolve(missing);
1165
+ if (/could not read|failed to traverse|bad object|missing/i.test(stderr))
1166
+ return resolve(true);
1167
+ reject(new CloudGitError(`\`git rev-list --objects\` failed: ${signal ? 'timed out' : stderr.trim() || `exit ${String(code)}`}`));
1168
+ });
1169
+ });
1170
+ }
1171
+ function historyUnavailable(missing, why) {
1172
+ const names = [...new Set(missing.map((tip) => tip.name))].join(', ');
1173
+ return new CloudGitError(`${HISTORY_UNAVAILABLE_CODE}: this deck's git history is not available yet${names ? ` (missing: ${names})` : ''}. ${why} ` +
1174
+ "Nothing was changed: the deck's files are fine, and git picks up again once the history is back.", EXIT_HISTORY_UNAVAILABLE);
1175
+ }
1176
+ function readSnapshotKey(dir) {
1177
+ try {
1178
+ return JSON.parse(fs.readFileSync(path.join(dir, SNAPSHOT_KEY_FILE), 'utf-8'));
1179
+ }
1180
+ catch {
1181
+ return null;
1182
+ }
1183
+ }
1184
+ function sameSnapshotKey(a, b) {
1185
+ return JSON.stringify([a.tips, a.mirrored, a.remoteMain, a.cap]) === JSON.stringify([b.tips, b.mirrored, b.remoteMain, b.cap]);
1186
+ }
1187
+ // Temp bundles are written inside .git/objects: the host's capture leaves that directory out
1188
+ // (an oversized temp file can never fail a checkpoint), it is on the same filesystem as the
1189
+ // snapshot for the rename, and git ignores a directory there it does not know.
1190
+ const SNAPSHOT_TMP_DIR = path.join('.git', 'objects', 'castle-tmp');
1191
+ // Temp and lock files a killed write left, split parts and their refs from older builds (only
1192
+ // ever ours: the deck lock is held).
1193
+ function cleanSnapshotLeftovers(ctx, state) {
1194
+ const root = gitDir(ctx.dir);
1195
+ let names = [];
1196
+ try {
1197
+ names = fs.readdirSync(root);
1198
+ }
1199
+ catch {
1200
+ names = [];
1201
+ }
1202
+ for (const name of names) {
1203
+ const leftover = name.startsWith('castle-snapshot') && (/\.tmp/.test(name) || name.endsWith('.lock'));
1204
+ if (leftover || OLD_PART_FILE_RE.test(name))
1205
+ fs.rmSync(path.join(root, name), { force: true });
1206
+ }
1207
+ fs.rmSync(path.join(ctx.dir, SNAPSHOT_TMP_DIR), { recursive: true, force: true });
1208
+ for (const ref of state.refs) {
1209
+ if (ref.name.startsWith(OLD_PART_REF_PREFIX))
1210
+ run(ctx, ['update-ref', '-d', ref.name]);
1211
+ }
1212
+ }
1213
+ function createBundle(ctx, file, refs, not, timeoutMs) {
1214
+ fs.rmSync(file, { force: true });
1215
+ const args = ['bundle', 'create', '--quiet', file, ...refs, ...(not.length ? ['--not', ...not] : [])];
1216
+ let result;
1217
+ try {
1218
+ result = run(ctx, args, { timeoutMs });
1219
+ }
1220
+ catch (e) {
1221
+ fs.rmSync(file, { force: true });
1222
+ throw e;
1223
+ }
1224
+ if (result.status === 0)
1225
+ return 'ok';
1226
+ fs.rmSync(file, { force: true });
1227
+ if (/empty bundle/i.test(result.stderr))
1228
+ return 'empty';
1229
+ ctx.deps.warn(`Could not write the snapshot bundle (the previous one is kept): ${describeFailure(args, result)}`);
1230
+ return 'failed';
1231
+ }
1232
+ /**
1233
+ * Writes the snapshot: HEAD, MERGE_HEAD, ORIG_HEAD and every local ref, minus what the floor
1234
+ * reaches -- refs/castle/mirrored, or castle/main when that one comes out over the cap (pushed
1235
+ * objects are on code.storage). Still over the cap: no snapshot at all, and the key file says
1236
+ * which tips were left out. Nothing it is written from changed: nothing is done at all, not
1237
+ * even a git command. A new bundle is renamed over the old one (never removed first), and the
1238
+ * key is written last. Only for a deck whose history is known to be here.
1239
+ */
1240
+ function writeSnapshotBundle(ctx, timeoutMs, state) {
1241
+ cleanSnapshotLeftovers(ctx, state);
1242
+ let tips = localTips(state);
1243
+ const mirrored = stateRef(state, MIRRORED_REF);
1244
+ const remoteMain = stateRef(state, REMOTE_MAIN);
1245
+ const cap = snapshotCap(ctx);
1246
+ const keyOf = (list) => ({ tips: list.map((t) => `${t.sha} ${t.name}`), mirrored, remoteMain, cap });
1247
+ let key = keyOf(tips);
1248
+ const file = path.join(ctx.dir, SNAPSHOT_BUNDLE_FILE);
1249
+ const old = readSnapshotKey(ctx.dir);
1250
+ const unchanged = () => old && sameSnapshotKey(old, key) && (old.skipped || fs.existsSync(file) === Boolean(old.written));
1251
+ if (unchanged())
1252
+ return 'unchanged';
1253
+ // ORIG_HEAD is only a convenience: one naming a missing object would fail every bundle write.
1254
+ if (state.origHead && missingTips(ctx, [{ name: 'ORIG_HEAD', sha: state.origHead }]).length > 0) {
1255
+ fs.rmSync(path.join(gitDir(ctx.dir), 'ORIG_HEAD'), { force: true });
1256
+ tips = tips.filter((tip) => tip.name !== 'ORIG_HEAD');
1257
+ key = keyOf(tips);
1258
+ if (unchanged())
1259
+ return 'unchanged';
1260
+ }
1261
+ const keyFile = path.join(ctx.dir, SNAPSHOT_KEY_FILE);
1262
+ if (tips.length === 0) {
1263
+ fs.rmSync(file, { force: true });
1264
+ writeJsonAtomic(keyFile, { ...key, written: false });
1265
+ return 'empty';
1266
+ }
1267
+ // A floor already found too low for these tips' growing set is not tried again.
1268
+ const mirrorOverCap = old?.mirrorOverCap && old.mirrorOverCap === mirrored ? mirrored : undefined;
1269
+ const floors = [];
1270
+ if (mirrored && !mirrorOverCap)
1271
+ floors.push(MIRRORED_REF);
1272
+ if (remoteMain && remoteMain !== mirrored)
1273
+ floors.push(REMOTE_MAIN);
1274
+ if (floors.length === 0 && mirrored)
1275
+ floors.push(MIRRORED_REF);
1276
+ const attempts = floors.length ? floors : [null];
1277
+ fs.mkdirSync(path.join(ctx.dir, SNAPSHOT_TMP_DIR), { recursive: true });
1278
+ const tmp = path.join(ctx.dir, SNAPSHOT_TMP_DIR, 'castle-snapshot.bundle.tmp');
1279
+ let overMirror = mirrorOverCap ?? undefined;
1280
+ try {
1281
+ for (const floor of attempts) {
1282
+ const result = createBundle(ctx, tmp, tips.map((t) => t.name), floor ? [floor] : [], timeoutMs);
1283
+ if (result === 'failed')
1284
+ return 'failed';
1285
+ if (result === 'empty') {
1286
+ fs.rmSync(file, { force: true });
1287
+ writeJsonAtomic(keyFile, { ...key, written: false, ...(overMirror ? { mirrorOverCap: overMirror } : {}) });
1288
+ return 'empty';
1289
+ }
1290
+ if (fileSize(tmp) <= cap) {
1291
+ fs.renameSync(tmp, file);
1292
+ writeJsonAtomic(keyFile, { ...key, written: true, ...(overMirror ? { mirrorOverCap: overMirror } : {}) });
1293
+ return 'written';
1294
+ }
1295
+ if (floor === MIRRORED_REF && mirrored)
1296
+ overMirror = mirrored;
1297
+ fs.rmSync(tmp, { force: true });
1298
+ }
1299
+ }
1300
+ finally {
1301
+ fs.rmSync(path.join(ctx.dir, SNAPSHOT_TMP_DIR), { recursive: true, force: true });
1302
+ }
1303
+ fs.rmSync(file, { force: true });
1304
+ writeJsonAtomic(keyFile, {
1305
+ ...key,
1306
+ written: false,
1307
+ ...(overMirror ? { mirrorOverCap: overMirror } : {}),
1308
+ skipped: { tips: Object.fromEntries(tips.map((t) => [t.name, t.sha])), reason: 'over_cap', at: new Date(ctx.deps.now()).toISOString() },
1309
+ });
1310
+ ctx.deps.warn(`The snapshot bundle would be over ${Math.round(cap / 1024 / 1024)} MB even above castle/main, so there is none: unpushed commits are safe once pushed.`);
1311
+ return 'skipped';
1312
+ }
1313
+ /**
1314
+ * Moves refs/castle/mirrored to what ghost says the mirror has, when that commit is here and
1315
+ * either follows the current floor or is part of castle/main (a force-push from a laptop can
1316
+ * leave the old floor off the remote's line; a floor that moves back only makes the bundle
1317
+ * bigger, never unsafe). True when it moved.
1318
+ */
1319
+ function advanceMirrorFloor(ctx, mainSha, state) {
1320
+ if (!mainSha || !OBJECT_ID_RE.test(mainSha))
1321
+ return false;
1322
+ const old = stateRef(state, MIRRORED_REF);
1323
+ if (old === mainSha)
1324
+ return false;
1325
+ if (!ok(ctx, ['cat-file', '-e', `${mainSha}^{commit}`]))
1326
+ return false;
1327
+ const remote = stateRef(state, REMOTE_MAIN);
1328
+ const forward = old !== null && ok(ctx, ['merge-base', '--is-ancestor', old, mainSha]);
1329
+ const onRemote = remote !== null && ok(ctx, ['merge-base', '--is-ancestor', mainSha, remote]);
1330
+ // Never backwards: a commit off the current floor's line only replaces a floor that is itself
1331
+ // off castle/main's.
1332
+ if (old && !forward && (!onRemote || (remote !== null && ok(ctx, ['merge-base', '--is-ancestor', old, remote]))))
1333
+ return false;
1334
+ return ok(ctx, ['update-ref', '-m', 'castle: mirror state', MIRRORED_REF, mainSha, old ?? '']);
1335
+ }
1336
+ // Before a command's git work: the deck's refs, read once and handed on. With history missing
1337
+ // it starts a background rehydrate -- never on leave -- and throws GIT_HISTORY_UNAVAILABLE.
1338
+ function requireHistory(ctx, opts) {
1339
+ repairGitSkeleton(ctx.dir);
1340
+ const state = readRefState(ctx);
1341
+ const missing = historyMissing(ctx, state);
1342
+ if (missing.length === 0)
1343
+ return state;
1344
+ if (opts.leave)
1345
+ throw historyUnavailable(missing, 'The leave commit does not rebuild history, so it was skipped.');
1346
+ throw historyUnavailable(missing, startBackgroundRehydrate(ctx));
1347
+ }
1348
+ // When castle/main moved since the last question, or it has been a while: ghost's
1349
+ // gitMirrorState. Asked before the deck lock is taken -- never while holding it -- from what
1350
+ // the last snapshot key recorded; the answer is applied under the lock. `always` for a sync
1351
+ // (ghost pokes the sync route after each mirror run). Undefined: not asked.
1352
+ const MIRROR_QUERY_FILE = path.join('.git', 'castle-mirror-query.json');
1353
+ const MIRROR_QUERY_INTERVAL_MS = 5 * 60_000;
1354
+ async function askMirrorIfDue(ctx, opts) {
1355
+ const mirror = ctx.deps.mirrorState;
1356
+ if (!mirror)
1357
+ return undefined;
1358
+ const key = readSnapshotKey(ctx.dir);
1359
+ if (!key?.remoteMain || key.mirrored === key.remoteMain)
1360
+ return undefined;
1361
+ let last = null;
1362
+ try {
1363
+ last = JSON.parse(fs.readFileSync(path.join(ctx.dir, MIRROR_QUERY_FILE), 'utf-8'));
1364
+ }
1365
+ catch {
1366
+ last = null;
1367
+ }
1368
+ const due = opts.always || !last || last.remoteMain !== key.remoteMain || ctx.deps.now() - (last.at ?? 0) >= MIRROR_QUERY_INTERVAL_MS;
1369
+ if (!due)
1370
+ return undefined;
1371
+ const deckId = readDeckId(ctx.dir);
1372
+ if (!deckId)
1373
+ return undefined;
1374
+ try {
1375
+ writeJsonAtomic(path.join(ctx.dir, MIRROR_QUERY_FILE), { remoteMain: key.remoteMain, at: ctx.deps.now() });
1376
+ return await withTimeout(mirror(deckId, { includeBundles: false, timeoutMs: MIRROR_STATE_TIMEOUT_MS }), MIRROR_STATE_TIMEOUT_MS + 500, 'gitMirrorState');
1377
+ }
1378
+ catch (e) {
1379
+ ctx.deps.log(`Could not ask for the deck's mirror state (the snapshot keeps its floor): ${errorText(e)}`);
1380
+ return undefined;
1381
+ }
1382
+ }
1383
+ // The key file tells the host's checkpoint it may leave `.git/objects` out. A write that fails
1384
+ // leaves the previous bundle and key in place (and creates no key where there was none): a
1385
+ // checkpoint that carried the objects could trip the host's per-file limit and lose the deck's
1386
+ // files, while a stale bundle risks only the newest commits' history -- which the leave commit
1387
+ // usually pushes, and a recovery keeps the files of.
1388
+ // After a command's git work: apply the mirror answer asked for before the lock, then rewrite
1389
+ // the bundle if anything it is written from changed. `state` is the command's own when it
1390
+ // changed no ref. Never fails the command.
1391
+ function refreshSnapshot(ctx, leave, opts = {}) {
1392
+ try {
1393
+ let state = opts.state ?? readRefState(ctx);
1394
+ if (!leave && opts.mirror && advanceMirrorFloor(ctx, opts.mirror.mainSha, state))
1395
+ state = readRefState(ctx);
1396
+ if (writeSnapshotBundle(ctx, leave ? LEAVE_BUNDLE_TIMEOUT_MS : BUNDLE_TIMEOUT_MS, state) === 'failed') {
1397
+ ctx.deps.warn('The snapshot bundle was not updated; the previous one (and its key file) stay.');
1398
+ }
1399
+ }
1400
+ catch (e) {
1401
+ ctx.deps.warn(`Could not refresh the snapshot bundle (the previous one and its key file stay): ${errorText(e)}`);
1402
+ }
1403
+ }
1404
+ function bootId() {
1405
+ try {
1406
+ return fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf-8').trim() || null;
1407
+ }
1408
+ catch {
1409
+ return null;
1410
+ }
1411
+ }
1412
+ /** This container's rehydrate backoff; state another host (or boot) wrote does not count. */
1413
+ export function readRehydrateState(dir, host = os.hostname()) {
1414
+ try {
1415
+ const state = JSON.parse(fs.readFileSync(path.join(dir, REHYDRATE_STATE_FILE), 'utf-8'));
1416
+ if (typeof state.failures !== 'number' || typeof state.nextAttemptAt !== 'number')
1417
+ return null;
1418
+ if (state.host !== host)
1419
+ return null;
1420
+ const boot = bootId();
1421
+ if (state.bootId && boot && state.bootId !== boot)
1422
+ return null;
1423
+ return state;
1424
+ }
1425
+ catch {
1426
+ return null;
1427
+ }
1428
+ }
1429
+ function recordRehydrateFailure(ctx, message) {
1430
+ try {
1431
+ const host = ctx.deps.hostname();
1432
+ const failures = (readRehydrateState(ctx.dir, host)?.failures ?? 0) + 1;
1433
+ const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** Math.min(failures - 1, 10));
1434
+ writeJsonAtomic(path.join(ctx.dir, REHYDRATE_STATE_FILE), {
1435
+ failures,
1436
+ lastFailureAt: new Date(ctx.deps.now()).toISOString(),
1437
+ nextAttemptAt: ctx.deps.now() + delay,
1438
+ lastError: message.slice(0, 2000),
1439
+ host,
1440
+ bootId: bootId(),
1441
+ });
1442
+ }
1443
+ catch {
1444
+ /* best effort */
1445
+ }
1446
+ }
1447
+ function rehydrateRunning(ctx) {
1448
+ try {
1449
+ const seen = inspectLock(path.join(ctx.dir, REHYDRATE_LOCK_FILE));
1450
+ return seen !== null && !holderIsGone(ctx.deps, seen);
1451
+ }
1452
+ catch {
1453
+ return false;
1454
+ }
1455
+ }
1456
+ function tryRehydrateLock(ctx) {
1457
+ try {
1458
+ return acquireLockFile(path.join(ctx.dir, REHYDRATE_LOCK_FILE), ctx.deps, 0);
1459
+ }
1460
+ catch (e) {
1461
+ if (e instanceof CloudGitError)
1462
+ return null;
1463
+ throw e;
1464
+ }
1465
+ }
1466
+ const CLI_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.js');
1467
+ /** Starts `castle-web git rehydrate` for the deck in its own session, its output to REHYDRATE_LOG_FILE. */
1468
+ export function spawnDetachedRehydrate(dir, env) {
1469
+ const log = path.join(dir, REHYDRATE_LOG_FILE);
1470
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1471
+ if (fileSize(log) > REHYDRATE_LOG_MAX_BYTES)
1472
+ fs.rmSync(log, { force: true });
1473
+ const fd = fs.openSync(log, 'a');
1474
+ try {
1475
+ const childEnv = { ...env };
1476
+ // Not this command's deadline: the rehydrate has its own budget.
1477
+ delete childEnv[DEADLINE_ENV];
1478
+ const child = spawn(process.execPath, [CLI_ENTRY, 'git', 'rehydrate', '--dir', dir], {
1479
+ cwd: dir,
1480
+ env: childEnv,
1481
+ detached: true,
1482
+ stdio: ['ignore', fd, fd],
1483
+ });
1484
+ child.on('error', () => undefined);
1485
+ child.unref();
1486
+ }
1487
+ finally {
1488
+ fs.closeSync(fd);
1489
+ }
1490
+ }
1491
+ // Starts a background rehydrate unless one is running, the last failure's backoff has not
1492
+ // passed, or it is switched off. Says which, for the error message.
1493
+ function startBackgroundRehydrate(ctx) {
1494
+ if (ctx.deps.env[BACKGROUND_REHYDRATE_ENV] === 'off')
1495
+ return 'Background rehydrate is switched off here.';
1496
+ if (rehydrateRunning(ctx))
1497
+ return 'A rehydrate is already fetching it.';
1498
+ const state = readRehydrateState(ctx.dir, ctx.deps.hostname());
1499
+ if (state && state.nextAttemptAt > ctx.deps.now()) {
1500
+ return `The last rehydrate failed (${state.lastError.slice(0, 200)}); the next try is after ${new Date(state.nextAttemptAt).toISOString()}.`;
1501
+ }
1502
+ try {
1503
+ (ctx.deps.spawnRehydrate ?? spawnDetachedRehydrate)(ctx.dir, ctx.deps.env);
1504
+ return `A rehydrate started in the background (log: ${REHYDRATE_LOG_FILE}).`;
1505
+ }
1506
+ catch (e) {
1507
+ return `Could not start a rehydrate: ${errorText(e)}.`;
1508
+ }
1509
+ }
1510
+ // Scratch directories a killed rehydrate left in the temp dir: named for their process, removed
1511
+ // once that process is gone and they are older than a whole rehydrate.
1512
+ function sweepScratchDirs(ctx) {
1513
+ const root = os.tmpdir();
1514
+ let names;
1515
+ try {
1516
+ names = fs.readdirSync(root);
1517
+ }
1518
+ catch {
1519
+ return;
1520
+ }
1521
+ for (const name of names) {
1522
+ if (!name.startsWith(SCRATCH_PREFIX))
1523
+ continue;
1524
+ const pid = Number(name.slice(SCRATCH_PREFIX.length).split('-')[0]);
1525
+ const full = path.join(root, name);
1526
+ try {
1527
+ if (Number.isInteger(pid) && pid > 0 && ctx.deps.isAlive(pid))
1528
+ continue;
1529
+ if (ctx.deps.now() - fs.statSync(full).mtimeMs < REHYDRATE_BUDGET_MS)
1530
+ continue;
1531
+ fs.rmSync(full, { recursive: true, force: true });
1532
+ }
1533
+ catch {
1534
+ /* best effort */
1535
+ }
1536
+ }
1537
+ }
1538
+ // Room for a download in the temp dir and for its pack in the deck's object store.
1539
+ function requireFreeSpace(dirs, bytes) {
1540
+ for (const dir of dirs) {
1541
+ let free;
1542
+ try {
1543
+ const stat = fs.statfsSync(dir);
1544
+ free = stat.bavail * stat.bsize;
1545
+ }
1546
+ catch {
1547
+ continue;
1548
+ }
1549
+ if (free < bytes + FREE_SPACE_MARGIN_BYTES)
1550
+ throw new Error(`not enough free disk in ${dir} for a ${bytes}-byte mirror bundle`);
1551
+ }
1552
+ }
1553
+ // Brings back objects only -- into the deck's object store, through a scratch repo with refs of
1554
+ // its own (the deck's refs name missing objects, which git's fetch and bundle checks refuse). No
1555
+ // ref of the deck changes here, and the deck lock is not held; finishRehydrate takes it.
1556
+ async function rehydrateObjects(ctx, budgetEnd) {
1557
+ const within = (cap) => {
1558
+ const left = budgetEnd - ctx.deps.now();
1559
+ if (left < MIN_STEP_MS)
1560
+ throw new Error('the rehydrate ran out of time');
1561
+ return Math.min(cap, left);
1562
+ };
1563
+ const result = {
1564
+ checkpointRemoteMain: refValue(ctx, REMOTE_MAIN),
1565
+ checkpointIntegrated: refValue(ctx, INTEGRATED_REF),
1566
+ remoteFetched: false,
1567
+ remoteMain: null,
1568
+ mirror: 'skipped',
1569
+ mirrorMain: null,
1570
+ snapshotOk: true,
1571
+ aborted: false,
1572
+ notes: [],
1573
+ used: [],
1574
+ };
1575
+ // Outside the deck: a draft checkpoint taken meanwhile must not carry downloads or scratch refs.
1576
+ const scratchRoot = fs.mkdtempSync(path.join(os.tmpdir(), `${SCRATCH_PREFIX}${ctx.deps.pid}-`));
1577
+ const scratch = path.join(scratchRoot, 'repo.git');
1578
+ const objects = path.join(gitDir(ctx.dir), 'objects');
1579
+ const inScratch = (args, timeoutMs) => run(ctx, ['--git-dir', scratch, ...SCRATCH_CONFIG, ...args], { timeoutMs, env: { GIT_OBJECT_DIRECTORY: objects } });
1580
+ const scratchRef = (ref) => {
1581
+ const r = inScratch(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
1582
+ return r.status === 0 ? r.stdout.trim() : null;
1583
+ };
1584
+ const stillMissing = () => historyMissing(ctx).length > 0;
1585
+ let pins = 0;
1586
+ // A bundle's prerequisites count only when a ref of the repo reaches them.
1587
+ const pinPresent = () => {
1588
+ const tips = requiredTips(readRefState(ctx));
1589
+ const gone = new Set(missingTips(ctx, tips).map((tip) => tip.sha));
1590
+ for (const tip of tips)
1591
+ if (!gone.has(tip.sha))
1592
+ inScratch(['update-ref', `refs/castle-local/${pins++}`, tip.sha]);
1593
+ };
1594
+ // Unbundled, not fetched: a fetch skips a bundle whose refs are all here already, and would
1595
+ // leave MERGE_HEAD's objects behind with it.
1596
+ const applySnapshot = () => {
1597
+ const file = path.join(ctx.dir, SNAPSHOT_BUNDLE_FILE);
1598
+ if (!fs.existsSync(file))
1599
+ return true;
1600
+ pinPresent();
1601
+ const unbundled = inScratch(['bundle', 'unbundle', file], within(REHYDRATE_STEP_MS));
1602
+ if (unbundled.status !== 0) {
1603
+ result.notes.push(describeFailure(['bundle', 'unbundle', path.basename(file)], unbundled));
1604
+ return false;
1605
+ }
1606
+ if (!result.used.includes('the snapshot bundle'))
1607
+ result.used.push('the snapshot bundle');
1608
+ return true;
1609
+ };
1610
+ try {
1611
+ must(ctx, ['init', '--quiet', '--bare', scratch]);
1612
+ // 1. The Castle remote (code.storage, through the llm-proxy).
1613
+ const url = configuredRemoteUrl(ctx);
1614
+ if (url) {
1615
+ const fetched = inScratch(['fetch', '--quiet', '--no-tags', url, '+refs/heads/*:refs/castle-remote/*'], within(REHYDRATE_STEP_MS));
1616
+ if (fetched.status === 0) {
1617
+ result.remoteFetched = true;
1618
+ result.remoteMain = scratchRef('refs/castle-remote/main');
1619
+ result.used.push('the Castle remote');
1620
+ }
1621
+ else {
1622
+ result.notes.push(describeFailure(['fetch', GIT_REMOTE_NAME], fetched));
1623
+ }
1624
+ }
1625
+ else {
1626
+ result.notes.push('no Castle remote is configured');
1627
+ }
1628
+ // 2. Local work nobody else has: the snapshot bundle.
1629
+ if (stillMissing())
1630
+ result.snapshotOk = applySnapshot();
1631
+ // 3. Still missing: the S3 mirror's chain, then the snapshot again on top of it.
1632
+ if (stillMissing()) {
1633
+ result.mirror = 'failed';
1634
+ const deckId = deckIdFor(ctx);
1635
+ const mirror = ctx.deps.mirrorState;
1636
+ const download = ctx.deps.download;
1637
+ if (!deckId || !mirror || !download) {
1638
+ result.notes.push('the S3 mirror cannot be asked from here');
1639
+ }
1640
+ else {
1641
+ const timeoutMs = within(MIRROR_BUNDLES_TIMEOUT_MS);
1642
+ const state = await withTimeout(mirror(deckId, { includeBundles: true, timeoutMs }), timeoutMs + 500, 'gitMirrorState');
1643
+ const bundles = state?.bundles ?? [];
1644
+ if (state && !state.mainSha && bundles.length === 0) {
1645
+ result.mirror = 'none';
1646
+ result.notes.push('the S3 mirror has nothing for this deck yet');
1647
+ }
1648
+ else if (bundles.length === 0) {
1649
+ result.notes.push('the S3 mirror listed no bundles');
1650
+ }
1651
+ else {
1652
+ for (const [i, entry] of bundles.entries()) {
1653
+ const file = path.join(scratchRoot, `mirror-${i}.bundle`);
1654
+ const stepMs = within(REHYDRATE_STEP_MS);
1655
+ // The download lands in the temp dir, its pack in the deck's object store.
1656
+ requireFreeSpace([scratchRoot, objects], entry.bytes ?? 0);
1657
+ await withTimeout(download(entry.url, file, { timeoutMs: stepMs, bytes: entry.bytes, sha256: entry.sha256 }), stepMs + 500, `downloading mirror bundle ${i + 1}`);
1658
+ // One fetch per chain entry; its prerequisites are the refs the earlier ones left.
1659
+ const fetched = inScratch(['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', file, `refs/*:refs/castle-mirror/${i}/*`], within(REHYDRATE_STEP_MS));
1660
+ fs.rmSync(file, { force: true });
1661
+ if (fetched.status !== 0)
1662
+ throw new Error(describeFailure(['fetch', `<mirror bundle ${i + 1}>`], fetched));
1663
+ }
1664
+ for (let i = bundles.length - 1; i >= 0 && !result.mirrorMain; i--) {
1665
+ result.mirrorMain = scratchRef(`refs/castle-mirror/${i}/heads/main`);
1666
+ }
1667
+ result.mirror = 'complete';
1668
+ result.used.push(`the S3 mirror (${bundles.length} bundle${bundles.length === 1 ? '' : 's'})`);
1669
+ }
1670
+ if (result.mirror !== 'failed')
1671
+ result.snapshotOk = applySnapshot();
1672
+ }
1673
+ }
1674
+ }
1675
+ catch (e) {
1676
+ result.aborted = true;
1677
+ result.notes.push(errorText(e));
1678
+ }
1679
+ finally {
1680
+ fs.rmSync(scratchRoot, { recursive: true, force: true });
1681
+ }
1682
+ return result;
1683
+ }
1684
+ // --- rehydrate: settling the deck's refs
1685
+ // Index entries (stage 0; conflict stages come from commits) whose blob is gone are hashed again
1686
+ // from the file on disk. A file that is gone, or no longer a file, leaves the index. Only the
1687
+ // index changes, never the file.
1688
+ function repairIndexBlobs(ctx) {
1689
+ const listed = run(ctx, ['ls-files', '--stage', '-z']);
1690
+ if (listed.status !== 0)
1691
+ return [];
1692
+ const entries = [];
1693
+ for (const record of listed.stdout.split('\0')) {
1694
+ const tab = record.indexOf('\t');
1695
+ if (tab < 0)
1696
+ continue;
1697
+ const [mode, sha, stage] = record.slice(0, tab).split(' ');
1698
+ if (stage === '0' && mode !== '160000' && sha)
1699
+ entries.push({ mode, sha, path: record.slice(tab + 1) });
1700
+ }
1701
+ if (entries.length === 0)
1702
+ return [];
1703
+ const check = run(ctx, ['cat-file', '--batch-check=%(objectname)'], { input: entries.map((e) => e.sha).join('\n') + '\n' });
1704
+ if (check.status !== 0)
1705
+ return [];
1706
+ const out = check.stdout.split('\n');
1707
+ const repaired = [];
1708
+ entries.forEach((entry, i) => {
1709
+ if (OBJECT_ID_RE.test((out[i] ?? '').trim()))
1710
+ return;
1711
+ let stat = null;
1712
+ try {
1713
+ stat = fs.lstatSync(path.join(ctx.dir, entry.path));
1714
+ }
1715
+ catch {
1716
+ stat = null;
1717
+ }
1718
+ let sha = null;
1719
+ let mode = entry.mode;
1720
+ if (stat?.isSymbolicLink()) {
1721
+ sha = must(ctx, ['hash-object', '-w', '--stdin'], { input: fs.readlinkSync(path.join(ctx.dir, entry.path)) }).trim();
1722
+ mode = '120000';
1723
+ }
1724
+ else if (stat?.isFile()) {
1725
+ sha = must(ctx, ['hash-object', '-w', '--', entry.path]).trim();
1726
+ if (mode === '120000')
1727
+ mode = '100644';
1728
+ }
1729
+ if (sha !== entry.sha) {
1730
+ if (sha)
1731
+ must(ctx, ['update-index', '--cacheinfo', `${mode},${sha},${entry.path}`]);
1732
+ else
1733
+ must(ctx, ['update-index', '--force-remove', '--', entry.path]);
1734
+ }
1735
+ repaired.push(entry.path);
1736
+ });
1737
+ return repaired;
1738
+ }
1739
+ // The snapshot that could not help is kept aside -- one generation, and only if it is under the
1740
+ // cap, so the snapshot and it stay under twice the cap together -- before the deck goes on
1741
+ // without it.
1742
+ function setAsideSnapshot(ctx) {
1743
+ const root = gitDir(ctx.dir);
1744
+ for (const name of fs.readdirSync(root))
1745
+ if (LOST_BUNDLE_RE.test(name))
1746
+ fs.rmSync(path.join(root, name), { force: true });
1747
+ const file = path.join(ctx.dir, SNAPSHOT_BUNDLE_FILE);
1748
+ fs.rmSync(path.join(ctx.dir, SNAPSHOT_KEY_FILE), { force: true });
1749
+ if (!fs.existsSync(file))
1750
+ return null;
1751
+ if (fileSize(file) > snapshotCap(ctx)) {
1752
+ fs.rmSync(file, { force: true });
1753
+ return null;
1754
+ }
1755
+ const to = path.join(root, `castle-lost-${ctx.deps.now()}-0.bundle`);
1756
+ fs.renameSync(file, to);
1757
+ return path.relative(ctx.dir, to);
1758
+ }
1759
+ function readHistoryRecovered(dir) {
1760
+ try {
1761
+ return JSON.parse(fs.readFileSync(path.join(dir, HISTORY_RECOVERED_FILE), 'utf-8'));
1762
+ }
1763
+ catch {
1764
+ return null;
1765
+ }
1766
+ }
1767
+ export function recoveredConflictInstruction(files) {
1768
+ return [
1769
+ "[Castle] This deck's local git history was lost -- it was never pushed and could not be found anywhere -- while a merge with changes from another computer was waiting to be resolved. Every file is exactly as it was.",
1770
+ ...(files
1771
+ ? ['These files still have conflict markers (<<<<<<< / ||||||| / ======= / >>>>>>>):', files.map((f) => ` - ${f}`).join('\n') || ' (none listed)']
1772
+ : ['Which files still have conflict markers (<<<<<<< / ||||||| / ======= / >>>>>>>) could not be checked: look through every file of the deck for them.']),
1773
+ "Resolve it now. Spawn one task agent to open each file, remove every marker so the file is whole and working again, preferring the other computer's side. Do not run git reset, rebase, checkout, merge or push. When no markers remain, finish with `castle-web commit --resolve -m \"Edits restored after lost history\"`; if it exits 3, it names the files that still have markers.",
1774
+ 'Then tell the user briefly that some unsaved history was lost but their files were kept.',
1775
+ ].join('\n');
1776
+ }
1777
+ export function historyLostInstruction(lost) {
1778
+ return [
1779
+ `[Castle] Part of this deck's git history was lost: commits that were never pushed (${lost.join(', ')}) were in neither the Castle remote, its backup nor the snapshot the sandbox keeps. No file was lost -- every file is exactly as it was. The next save commits them and brings in anything pushed from elsewhere since; where both sides changed the same thing, that comes back as an ordinary merge conflict to resolve.`,
1780
+ 'Nothing needs fixing now. Tell the user in one plain sentence that some of the in-between save points from their last session could not be restored, but their current work is intact.',
1781
+ ].join('\n');
1782
+ }
1783
+ // Text files of the deck (tracked or not, excludes respected) with conflict-marker lines, for a
1784
+ // merge whose record is gone. Bounded in time and count.
1785
+ const MARKER_SCAN_LIMIT = 200;
1786
+ // A file counts when it has both an opening and a closing marker line. Null: the scan itself
1787
+ // failed or ran out of time -- unknown, never "no conflict".
1788
+ function filesWithConflictMarkers(ctx) {
1789
+ let result;
1790
+ try {
1791
+ result = run(ctx, ['grep', '-l', '-I', '--untracked', '-E', '^<{7}( |$)'], { timeoutMs: 10_000 });
1792
+ }
1793
+ catch {
1794
+ return null;
1795
+ }
1796
+ if (result.status === 1)
1797
+ return [];
1798
+ if (result.status !== 0)
1799
+ return null;
1800
+ const out = [];
1801
+ for (const file of lines(result.stdout).slice(0, MARKER_SCAN_LIMIT)) {
1802
+ let text;
1803
+ try {
1804
+ text = fs.readFileSync(path.join(ctx.dir, file), 'utf-8');
1805
+ }
1806
+ catch {
1807
+ continue;
1808
+ }
1809
+ if (/^>{7}( |$)/m.test(text))
1810
+ out.push({ path: file, stages: {}, kind: 'text', resolution: 'markers' });
1811
+ }
1812
+ return out;
1813
+ }
1814
+ // The terminal case (see finishRehydrate for when it may run): local commits nobody has. main
1815
+ // goes back to refs/castle/integrated -- the last remote version local main is known to have
1816
+ // contained, so the next sync is a real three-way merge with whatever came after it (never
1817
+ // castle/main: that may have been fetched and not merged, and starting from it would revert
1818
+ // what came in with it) -- and any other lost branch goes. Without that commit (gone, or a deck
1819
+ // from before it was recorded) main starts again unborn: the kept files are committed as a root
1820
+ // and merged with the remote's main as unrelated histories, so pushed work conflicts rather
1821
+ // than being overwritten. The index follows HEAD; the working tree
1822
+ // is never touched. A merge in progress whose side is lost leaves its conflicted files to the
1823
+ // agent (castle-merge.json), rather than having markers committed.
1824
+ async function recoverLostHistory(ctx, missing, result) {
1825
+ const integrated = result.checkpointIntegrated;
1826
+ const checkpointBase = integrated &&
1827
+ missingTips(ctx, [{ name: REMOTE_MAIN, sha: integrated }]).length === 0 &&
1828
+ !(await historyIncomplete(ctx, [integrated]))
1829
+ ? integrated
1830
+ : null;
1831
+ const skipped = readSnapshotKey(ctx.dir)?.skipped?.tips ?? {};
1832
+ const keptBundle = setAsideSnapshot(ctx);
1833
+ const lost = new Set(missing.map((tip) => tip.name));
1834
+ const headRef = run(ctx, ['symbolic-ref', '--quiet', 'HEAD']);
1835
+ const headBranch = headRef.status === 0 ? headRef.stdout.trim() : null;
1836
+ for (const tip of missing) {
1837
+ if (!tip.name.startsWith('refs/'))
1838
+ continue;
1839
+ if (tip.name === `refs/heads/${MAIN}` && checkpointBase)
1840
+ must(ctx, ['update-ref', '-m', 'castle: lost history', tip.name, checkpointBase]);
1841
+ else
1842
+ must(ctx, ['update-ref', '-d', tip.name]);
1843
+ }
1844
+ if (lost.has('HEAD') && headBranch !== `refs/heads/${MAIN}`) {
1845
+ must(ctx, ['symbolic-ref', 'HEAD', `refs/heads/${MAIN}`]);
1846
+ if (checkpointBase && !revParse(ctx, `refs/heads/${MAIN}`))
1847
+ must(ctx, ['update-ref', `refs/heads/${MAIN}`, checkpointBase]);
1848
+ }
1849
+ // Without a base the next merge with the remote's main finds no common commit, and joins the
1850
+ // histories as unrelated (integrate): both sides' changes meet as conflicts.
1851
+ const orig = refValue(ctx, 'ORIG_HEAD');
1852
+ if (orig && missingTips(ctx, [{ name: 'ORIG_HEAD', sha: orig }]).length > 0) {
1853
+ fs.rmSync(path.join(gitDir(ctx.dir), 'ORIG_HEAD'), { force: true });
1854
+ }
1855
+ const mergeLost = mergeInProgress(ctx.dir) && (lost.has('MERGE_HEAD') || lost.has('HEAD'));
1856
+ const state = mergeLost ? readMergeState(ctx.dir) : null;
1857
+ if (mergeLost) {
1858
+ for (const name of ['MERGE_HEAD', 'MERGE_MSG', 'MERGE_MODE', 'AUTO_MERGE']) {
1859
+ fs.rmSync(path.join(gitDir(ctx.dir), name), { force: true });
1860
+ }
1861
+ }
1862
+ const head = revParse(ctx, 'HEAD');
1863
+ must(ctx, head ? ['read-tree', head] : ['read-tree', '--empty']);
1864
+ let marked = (state?.files ?? [])
1865
+ .filter((f) => f.resolution === 'markers' || f.resolution === 'manual')
1866
+ .filter((f) => stillHasMarkers(ctx, f));
1867
+ // A merge whose record is gone: the files that still carry markers, found by looking. A scan
1868
+ // that failed leaves the whole deck to the agent.
1869
+ let unknown = false;
1870
+ if (mergeLost && !state) {
1871
+ const found = filesWithConflictMarkers(ctx);
1872
+ unknown = found === null;
1873
+ marked = found ?? [];
1874
+ }
1875
+ const conflict = marked.length > 0 || unknown;
1876
+ if (conflict) {
1877
+ const instruction = recoveredConflictInstruction(unknown ? null : marked.map((f) => f.path));
1878
+ const base = state ?? { at: new Date(ctx.deps.now()).toISOString(), head: '', mergeHead: '', files: [], instruction };
1879
+ writeJsonAtomic(mergeStatePath(ctx.dir), { ...base, files: marked, instruction, recovered: true });
1880
+ writeJsonAtomic(path.join(ctx.dir, CONFLICT_MARKER_FILE), {
1881
+ at: new Date(ctx.deps.now()).toISOString(),
1882
+ files: marked.map((f) => f.path),
1883
+ theirs: [],
1884
+ ours: [],
1885
+ instruction,
1886
+ });
1887
+ }
1888
+ else if (mergeLost) {
1889
+ fs.rmSync(mergeStatePath(ctx.dir), { force: true });
1890
+ }
1891
+ const at = new Date(ctx.deps.now()).toISOString();
1892
+ writeJsonAtomic(path.join(ctx.dir, HISTORY_RECOVERED_FILE), {
1893
+ at,
1894
+ lost: missing.map((tip) => ({ ref: tip.name, sha: tip.sha })),
1895
+ newHead: head,
1896
+ skippedOverCap: missing.filter((tip) => skipped[tip.name] === tip.sha).map((tip) => tip.name),
1897
+ conflict,
1898
+ keptBundle,
1899
+ reason: 'These commits were in neither the Castle remote (which answered), the S3 mirror nor the snapshot bundle. ' +
1900
+ "The deck's files were kept exactly as they were and are committed on top of the last pushed version.",
1901
+ tried: result.notes,
1902
+ committed: false,
1903
+ });
1904
+ // Told once, the way a conflict or an adopt is (a conflict's own notice already covers it).
1905
+ if (!conflict) {
1906
+ const shortLost = missing.filter((t) => isBranchTip(t.name)).map((t) => t.sha.slice(0, 10));
1907
+ writeJsonAtomic(path.join(ctx.dir, HISTORY_LOST_MARKER_FILE), {
1908
+ at,
1909
+ notice: 'Some unsaved history of this deck could not be restored; the files are intact.',
1910
+ instruction: historyLostInstruction([...new Set(shortLost)]),
1911
+ });
1912
+ }
1913
+ ctx.deps.warn(`Local git history was lost and could not be found anywhere (${missing.map((t) => `${t.name} ${t.sha.slice(0, 10)}`).join(', ')}). ` +
1914
+ `The deck's files are unchanged and will be committed on top of ${checkpointBase ? `the last pushed version this deck had (${checkpointBase.slice(0, 10)})` : "a new history, merged with the remote's main"}` +
1915
+ `${conflict ? ' once the agent resolves the conflict markers left in them' : ''}; details in ${HISTORY_RECOVERED_FILE}.`);
1916
+ }
1917
+ // Every sweep-able ref (tags, stash, remote-tracking, Castle's own) whose object is gone goes,
1918
+ // so no later fetch trips over it ("fatal: bad object").
1919
+ function dropBrokenRefs(ctx) {
1920
+ const refs = allRefs(ctx).filter((tip) => !isBranchTip(tip.name));
1921
+ for (const tip of missingTips(ctx, refs)) {
1922
+ run(ctx, ['update-ref', '-d', tip.name, tip.sha]);
1923
+ ctx.deps.warn(`Removed ${tip.name}: its object ${tip.sha.slice(0, 10)} is gone.`);
1924
+ }
1925
+ // ORIG_HEAD too: the snapshot bundles it, and cannot while it names nothing.
1926
+ const orig = readShaFile(path.join(gitDir(ctx.dir), 'ORIG_HEAD'));
1927
+ if (orig && missingTips(ctx, [{ name: 'ORIG_HEAD', sha: orig }]).length > 0) {
1928
+ fs.rmSync(path.join(gitDir(ctx.dir), 'ORIG_HEAD'), { force: true });
1929
+ }
1930
+ }
1931
+ // Under the deck lock, after rehydrateObjects: give up lost local commits only when every
1932
+ // source answered cleanly, settle castle/main and the other refs, check the history is whole,
1933
+ // and re-hash staged blobs. Throws GIT_HISTORY_UNAVAILABLE (nothing changed) otherwise.
1934
+ async function finishRehydrate(ctx, result) {
1935
+ const tried = () => `Tried: ${result.notes.join('; ') || 'nothing could be tried'}.`;
1936
+ const branches = historyMissing(ctx).filter((tip) => isBranchTip(tip.name));
1937
+ // Clean: the remote answered (an outage says nothing), the mirror applied its whole chain or
1938
+ // said it has none, the snapshot applied -- and the remote did not come back without a main
1939
+ // that the mirror or the checkpoint says it had.
1940
+ const clean = result.remoteFetched &&
1941
+ !result.aborted &&
1942
+ (result.mirror === 'complete' || result.mirror === 'none' || result.mirror === 'skipped') &&
1943
+ result.snapshotOk &&
1944
+ !(result.remoteMain === null && (result.mirrorMain !== null || result.checkpointRemoteMain !== null));
1945
+ const others = historyMissing(ctx).filter((tip) => !isBranchTip(tip.name));
1946
+ const localOnly = others.filter((tip) => !isCastleRef(tip.name));
1947
+ if ((branches.length > 0 || localOnly.length > 0) && !clean) {
1948
+ throw historyUnavailable([...branches, ...localOnly], tried());
1949
+ }
1950
+ if (branches.length > 0) {
1951
+ if (result.remoteMain && (await historyIncomplete(ctx, [result.remoteMain]))) {
1952
+ throw historyUnavailable(branches, `The remote's main is incomplete. ${tried()}`);
1953
+ }
1954
+ await recoverLostHistory(ctx, branches, result);
1955
+ }
1956
+ // castle/main is where the remote was last seen: kept while its commit is here (the next
1957
+ // sync fetches), else what was just fetched, else the mirror's main.
1958
+ const remote = refValue(ctx, REMOTE_MAIN);
1959
+ if (remote && missingTips(ctx, [{ name: REMOTE_MAIN, sha: remote }]).length > 0) {
1960
+ const to = result.remoteMain ?? result.mirrorMain;
1961
+ if (to)
1962
+ must(ctx, ['update-ref', '-m', 'castle: rehydrate', REMOTE_MAIN, to]);
1963
+ }
1964
+ else if (!remote && result.remoteMain) {
1965
+ must(ctx, ['update-ref', '-m', 'castle: rehydrate', REMOTE_MAIN, result.remoteMain]);
1966
+ }
1967
+ dropBrokenRefs(ctx);
1968
+ const tips = requiredTips(readRefState(ctx));
1969
+ const left = missingTips(ctx, tips);
1970
+ if (left.length > 0)
1971
+ throw historyUnavailable(left, tried());
1972
+ if (await historyIncomplete(ctx, tips.map((t) => t.sha))) {
1973
+ throw historyUnavailable([], `Some older commits or files are still missing. ${tried()}`);
1974
+ }
1975
+ const reindexed = repairIndexBlobs(ctx);
1976
+ // A snapshot of the rebuilt state (and its key file, which a recovery took away).
1977
+ refreshSnapshot(ctx, false);
1978
+ ctx.deps.log(`Rebuilt this deck's git history from ${result.used.join(', ') || 'what was already here'}` +
1979
+ (reindexed.length ? `; re-hashed ${reindexed.length} staged file(s) from disk.` : '.'));
1980
+ }
1981
+ // The whole rehydrate, under REHYDRATE_LOCK_FILE: objects first, without the deck lock, then
1982
+ // the deck's refs under it. Any failure is recorded for the backoff and surfaces as
1983
+ // GIT_HISTORY_UNAVAILABLE.
1984
+ async function runRehydrate(ctx) {
1985
+ repairGitSkeleton(ctx.dir);
1986
+ const release = tryRehydrateLock(ctx);
1987
+ if (!release)
1988
+ throw historyUnavailable(historyMissing(ctx), 'A rehydrate is already running for this deck.');
1989
+ try {
1990
+ sweepScratchDirs(ctx);
1991
+ const own = readDeckId(ctx.dir);
1992
+ const remoteId = remoteDeckId(ctx);
1993
+ if (own && remoteId && own !== remoteId) {
1994
+ // A copied deck: its history is another deck's. `git attach` starts it afresh instead.
1995
+ throw historyUnavailable(historyMissing(ctx), `Its Castle remote is deck ${remoteId}'s but this deck is ${own}; it is not rebuilt from there. Attach it to its own remote.`);
1996
+ }
1997
+ if (historyMissing(ctx).length === 0) {
1998
+ fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
1999
+ return 'complete';
2000
+ }
2001
+ const budgetEnd = ctx.deadline ?? ctx.deps.now() + REHYDRATE_BUDGET_MS;
2002
+ const result = await rehydrateObjects(ctx, budgetEnd);
2003
+ await withDeckLock(ctx, () => finishRehydrate(ctx, result));
2004
+ fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
2005
+ return 'rebuilt';
2006
+ }
2007
+ catch (e) {
2008
+ const error = e instanceof CloudGitError && e.exitCode === EXIT_HISTORY_UNAVAILABLE
2009
+ ? e
2010
+ : historyUnavailable([], `The rehydrate failed: ${errorText(e)}`);
2011
+ recordRehydrateFailure(ctx, error.message);
2012
+ throw error;
2013
+ }
2014
+ finally {
2015
+ release();
2016
+ }
2017
+ }
2018
+ // A copied deck (attached to another deck's remote) whose objects are gone: its history was the
2019
+ // other deck's, and is not rebuilt from there. Its refs and merge state go, the index empties,
2020
+ // and the attach goes on as for a fresh deck. The files are untouched.
2021
+ function dropForeignHistory(ctx, original) {
2022
+ for (const ref of allRefs(ctx))
2023
+ run(ctx, ['update-ref', '--no-deref', '-d', ref.name]);
2024
+ for (const name of ['MERGE_HEAD', 'MERGE_MSG', 'MERGE_MODE', 'AUTO_MERGE', 'ORIG_HEAD', 'FETCH_HEAD', MERGE_STATE_FILE]) {
2025
+ fs.rmSync(path.join(gitDir(ctx.dir), name), { force: true });
2026
+ }
2027
+ for (const rel of [LEAVE_PENDING_FILE, SNAPSHOT_KEY_FILE, REHYDRATE_STATE_FILE, SNAPSHOT_BUNDLE_FILE]) {
2028
+ fs.rmSync(path.join(ctx.dir, rel), { force: true });
2029
+ }
2030
+ must(ctx, ['symbolic-ref', 'HEAD', `refs/heads/${MAIN}`]);
2031
+ must(ctx, ['read-tree', '--empty']);
2032
+ ctx.deps.warn(`This copied deck's git history (deck ${original}'s) was not in its checkpoint; it starts a fresh history instead. Its files are unchanged.`);
2033
+ }
2034
+ /** `castle-web git rehydrate --dir <deck>`: rebuild a cold-resumed deck's git history. */
2035
+ export async function cloudRehydrate(dir, deps) {
2036
+ requireSandbox(deps, 'git rehydrate');
2037
+ const ctx = contextFor(dir, deps);
2038
+ try {
2039
+ if (!fs.lstatSync(gitDir(ctx.dir)).isDirectory())
2040
+ throw new Error('not a directory');
2041
+ }
2042
+ catch {
2043
+ throw new CloudGitError(`${ctx.dir} has no git repo to rehydrate.`, EXIT_NOT_ENABLED);
2044
+ }
2045
+ return runRehydrate(ctx);
2046
+ }
796
2047
  // Concludes the merge in progress as one whole commit -- only when no conflicted file still
797
2048
  // has markers. Git refuses a partial commit mid-merge, so named paths are not used.
798
2049
  function concludeMerge(ctx, opts, reason, identity) {
@@ -804,15 +2055,20 @@ function concludeMerge(ctx, opts, reason, identity) {
804
2055
  ctx.deps.warn('Concluding a merge commits the whole deck; the paths given were not needed.');
805
2056
  // Anything a leave commit could not save mid-merge is on disk still, and goes in with it.
806
2057
  must(ctx, ['add', '-A']);
807
- // No message of our own keeps git's "Merge changes from another computer" one.
2058
+ // No message of our own keeps git's "Merge changes from another computer" one. A recovered
2059
+ // conflict has no merge left, so no message of git's either.
808
2060
  const trailer = AGENT_REASONS.has(reason) ? ['--trailer', AGENT_TRAILER] : [];
2061
+ const merging = mergeInProgress(ctx.dir);
2062
+ const message = opts.message?.trim() || (merging ? '' : RECOVERED_COMMIT_MESSAGE);
809
2063
  must(ctx, [
810
2064
  ...identity,
811
2065
  'commit',
812
2066
  '--quiet',
813
2067
  '--no-verify',
814
- ...(opts.message?.trim() ? commitMessageArgs(opts, reason) : ['--no-edit', ...trailer]),
2068
+ ...(message ? commitMessageArgs({ ...opts, message }, reason) : ['--no-edit', ...trailer]),
815
2069
  ]);
2070
+ if (!merging)
2071
+ markRecoveredCommitted(ctx);
816
2072
  fs.rmSync(mergeStatePath(ctx.dir), { force: true });
817
2073
  fs.rmSync(path.join(ctx.dir, LEAVE_PENDING_FILE), { force: true });
818
2074
  }
@@ -840,9 +2096,15 @@ function recordLeavePending(ctx) {
840
2096
  ctx.deps.warn(`Could not note the uncommitted edits: ${e instanceof Error ? e.message : String(e)}`);
841
2097
  }
842
2098
  }
2099
+ function markRecoveredCommitted(ctx) {
2100
+ const recovered = readHistoryRecovered(ctx.dir);
2101
+ if (recovered && !recovered.committed) {
2102
+ writeJsonAtomic(path.join(ctx.dir, HISTORY_RECOVERED_FILE), { ...recovered, committed: true });
2103
+ }
2104
+ }
843
2105
  async function commitLocked(ctx, opts) {
844
2106
  const reason = opts.reason ?? 'manual';
845
- if (mergeInProgress(ctx.dir)) {
2107
+ if (mergeWaiting(ctx.dir)) {
846
2108
  // Nothing but an explicit --resolve lands mid-merge: a turn, task, leave or manual
847
2109
  // commit would otherwise conclude a merge nobody has checked.
848
2110
  if (!opts.resolve) {
@@ -856,8 +2118,17 @@ async function commitLocked(ctx, opts) {
856
2118
  // Left behind by a merge concluded (or aborted) some other way.
857
2119
  fs.rmSync(mergeStatePath(ctx.dir), { force: true });
858
2120
  fs.rmSync(path.join(ctx.dir, LEAVE_PENDING_FILE), { force: true });
859
- const identity = await identityArgs(ctx);
860
- const commit = (extra) => must(ctx, [...identity, 'commit', '--quiet', '--no-verify', ...extra]);
2121
+ // The first commit after a rehydrate gave up lost history says so.
2122
+ const recovered = readHistoryRecovered(ctx.dir);
2123
+ if (recovered && !recovered.committed && !opts.message?.trim())
2124
+ opts = { ...opts, message: RECOVERED_COMMIT_MESSAGE };
2125
+ // Looked up only once there is something to commit.
2126
+ const commit = async (extra) => {
2127
+ const identity = await identityArgs(ctx);
2128
+ must(ctx, [...identity, 'commit', '--quiet', '--no-verify', ...extra]);
2129
+ if (recovered && !recovered.committed)
2130
+ markRecoveredCommitted(ctx);
2131
+ };
861
2132
  if (opts.paths && opts.paths.length > 0) {
862
2133
  const specs = commitPathspecs(ctx, opts.paths);
863
2134
  if (specs.length === 0)
@@ -865,13 +2136,13 @@ async function commitLocked(ctx, opts) {
865
2136
  must(ctx, ['add', '-A', '--', ...specs]);
866
2137
  if (ok(ctx, ['diff', '--cached', '--quiet', '--', ...specs]))
867
2138
  return { sha: null };
868
- commit([...commitMessageArgs(opts, reason), '--', ...specs]);
2139
+ await commit([...commitMessageArgs(opts, reason), '--', ...specs]);
869
2140
  }
870
2141
  else {
871
2142
  must(ctx, ['add', '-A']);
872
2143
  if (ok(ctx, ['diff', '--cached', '--quiet']))
873
2144
  return { sha: null };
874
- commit(commitMessageArgs(opts, reason));
2145
+ await commit(commitMessageArgs(opts, reason));
875
2146
  }
876
2147
  return { sha: revParse(ctx, 'HEAD') };
877
2148
  }
@@ -882,7 +2153,11 @@ function requireMainBranch(ctx) {
882
2153
  }
883
2154
  }
884
2155
  function fetchRemote(ctx) {
885
- must(ctx, ['fetch', '--quiet', '--prune', '--no-tags', GIT_REMOTE_NAME], { timeoutMs: NETWORK_TIMEOUT_MS });
2156
+ // One pack per fetch: all or nothing, even when a fetch is killed partway.
2157
+ const args = ['fetch', '--quiet', '--prune', '--no-tags', GIT_REMOTE_NAME];
2158
+ const fetched = run(ctx, ['-c', 'fetch.unpackLimit=1', '-c', 'transfer.unpackLimit=1', ...args], { timeoutMs: NETWORK_TIMEOUT_MS });
2159
+ if (fetched.status !== 0)
2160
+ throw new CloudGitError(describeFailure(args, fetched));
886
2161
  return revParse(ctx, REMOTE_MAIN);
887
2162
  }
888
2163
  // Bring castle/main into local main. Local work is already committed by the caller.
@@ -895,7 +2170,17 @@ function deferIfBusy(ctx) {
895
2170
  ctx.deps.warn('Task agents started working in the deck; the remote\'s changes are merged once it is idle.');
896
2171
  return true;
897
2172
  }
2173
+ // A recovery that had no base left main unborn over files that are the deck's only copy of its
2174
+ // work: they are committed first, as a root commit, so the remote's main is merged with them
2175
+ // (unrelated histories: both sides meet as conflicts) instead of an adopt replacing them.
2176
+ async function commitRecoveredRoot(ctx) {
2177
+ const recovered = readHistoryRecovered(ctx.dir);
2178
+ if (!recovered || recovered.committed || revParse(ctx, 'HEAD'))
2179
+ return;
2180
+ await commitLocked(ctx, { reason: 'sync' });
2181
+ }
898
2182
  async function integrate(ctx, remote) {
2183
+ await commitRecoveredRoot(ctx);
899
2184
  const head = revParse(ctx, 'HEAD');
900
2185
  if (!head) {
901
2186
  if (deferIfBusy(ctx))
@@ -913,12 +2198,17 @@ async function integrate(ctx, remote) {
913
2198
  return 'fast-forward';
914
2199
  }
915
2200
  const identity = await identityArgs(ctx);
2201
+ // No common commit at all -- a recovery that had to start the deck's history afresh: the
2202
+ // histories are joined, and both sides' changes meet as conflicts rather than one replacing
2203
+ // the other.
2204
+ const unrelated = run(ctx, ['merge-base', 'HEAD', REMOTE_MAIN]).status === 1;
916
2205
  const merge = run(ctx, [
917
2206
  ...identity,
918
2207
  'merge',
919
2208
  '--no-edit',
920
2209
  '--no-ff',
921
2210
  '--quiet',
2211
+ ...(unrelated ? ['--allow-unrelated-histories'] : []),
922
2212
  '-X',
923
2213
  'diff-algorithm=histogram',
924
2214
  '-m',
@@ -945,10 +2235,21 @@ const PUSH_ARGS = ['push', '--quiet', GIT_REMOTE_NAME, `${MAIN}:refs/heads/${MAI
945
2235
  // sync's comparisons hold.
946
2236
  function pushMain(ctx, local) {
947
2237
  const push = run(ctx, PUSH_ARGS, { timeoutMs: NETWORK_TIMEOUT_MS });
948
- if (push.status === 0)
2238
+ if (push.status === 0) {
949
2239
  run(ctx, ['update-ref', REMOTE_MAIN, local]);
2240
+ markIntegrated(ctx, local);
2241
+ }
950
2242
  return push;
951
2243
  }
2244
+ /**
2245
+ * The remote's main as local main last took it in: what a recovery may start the deck again
2246
+ * from. castle/main can be ahead of it -- fetched, but its merge deferred while tasks were busy,
2247
+ * or refused -- and starting from castle/main would revert whatever came in with it.
2248
+ */
2249
+ export const INTEGRATED_REF = 'refs/castle/integrated';
2250
+ function markIntegrated(ctx, sha) {
2251
+ run(ctx, ['update-ref', '-m', 'castle: integrated', INTEGRATED_REF, sha]);
2252
+ }
952
2253
  function pushOnly(ctx) {
953
2254
  const local = revParse(ctx, 'HEAD');
954
2255
  if (!local || local === revParse(ctx, REMOTE_MAIN))
@@ -966,7 +2267,7 @@ async function syncLocked(ctx, opts) {
966
2267
  requireMainBranch(ctx);
967
2268
  if (opts.commitFirst)
968
2269
  await commitLocked(ctx, { reason: 'sync' });
969
- if (mergeInProgress(ctx.dir))
2270
+ if (mergeWaiting(ctx.dir))
970
2271
  throw mergeWaitingError(ctx);
971
2272
  if (opts.mode === 'push-only')
972
2273
  return pushOnly(ctx);
@@ -979,6 +2280,7 @@ async function syncLocked(ctx, opts) {
979
2280
  const step = await integrate(ctx, remote);
980
2281
  if (step === 'conflict' || step === 'deferred')
981
2282
  return { merge: step, pushed: false };
2283
+ markIntegrated(ctx, remote);
982
2284
  if (merge === 'none' || step !== 'none')
983
2285
  merge = step;
984
2286
  }
@@ -1222,13 +2524,20 @@ function adoptRemote(ctx) {
1222
2524
  return { backup: backup?.dir ?? null };
1223
2525
  }
1224
2526
  // --- the commands -----------------------------------------------------------
2527
+ // A deadline that cannot be meant (not epoch milliseconds, or more than a day out -- a caller
2528
+ // whose `date` misbehaved) counts as none, rather than having every step refuse to start. One
2529
+ // already past is kept: the caller's kill is about to land, and refusing every step is exactly
2530
+ // what the deadline is for.
2531
+ const MAX_DEADLINE_AHEAD_MS = 24 * 60 * 60_000;
1225
2532
  function contextFor(dir, deps) {
1226
2533
  const deadline = Number(deps.env[DEADLINE_ENV]);
2534
+ const startedAt = deps.now();
2535
+ const plausible = Number.isFinite(deadline) && deadline >= 1e12 && deadline <= startedAt + MAX_DEADLINE_AHEAD_MS;
1227
2536
  return {
1228
2537
  dir: path.resolve(dir),
1229
2538
  deps,
1230
- startedAt: deps.now(),
1231
- ...(Number.isFinite(deadline) && deadline > 0 ? { deadline } : {}),
2539
+ startedAt,
2540
+ ...(plausible ? { deadline } : {}),
1232
2541
  };
1233
2542
  }
1234
2543
  function syncModeFor(ctx, namedPaths) {
@@ -1256,21 +2565,44 @@ async function syncAfterCommit(ctx, mode) {
1256
2565
  export async function cloudCommit(dir, opts, deps) {
1257
2566
  const ctx = contextFor(dir, deps);
1258
2567
  requireAttached(ctx, 'commit');
2568
+ const reason = opts.reason ?? 'manual';
2569
+ const leave = reason === 'leave';
2570
+ // Never on the way out of a deck, and never while holding the deck lock.
2571
+ const mirror = leave ? undefined : await askMirrorIfDue(ctx, { always: false });
1259
2572
  return withDeckLock(ctx, async () => {
1260
- const reason = opts.reason ?? 'manual';
1261
- const outcome = await commitLocked(ctx, opts);
1262
- if (reason === 'sync')
1263
- return { ...outcome, sync: null };
1264
- const quiet = QUIET_REASONS.has(reason) &&
1265
- !opts.resolve &&
1266
- !outcome.sha &&
1267
- revParse(ctx, 'HEAD') === revParse(ctx, REMOTE_MAIN) &&
1268
- !syncPending(ctx);
1269
- if (quiet)
1270
- return { ...outcome, sync: null };
1271
- const after = await syncAfterCommit(ctx, syncModeFor(ctx, (opts.paths?.length ?? 0) > 0));
1272
- await packAfterCommit(ctx, reason);
1273
- return { ...outcome, ...after };
2573
+ // History missing: a background rehydrate starts (never on the way out of a deck) and this
2574
+ // stops at once. The host's checkpoint keeps the files meanwhile.
2575
+ const state = requireHistory(ctx, { leave });
2576
+ let outcome;
2577
+ try {
2578
+ outcome = await commitLocked(ctx, opts);
2579
+ }
2580
+ finally {
2581
+ // On the way out of a deck the bundle comes first, before any network.
2582
+ if (leave)
2583
+ refreshSnapshot(ctx, true, { state: outcome && !outcome.sha ? state : undefined });
2584
+ }
2585
+ // Whether no ref has moved since `state` was read.
2586
+ let untouched = !outcome.sha;
2587
+ try {
2588
+ if (reason === 'sync')
2589
+ return { ...outcome, sync: null };
2590
+ const quiet = QUIET_REASONS.has(reason) &&
2591
+ !opts.resolve &&
2592
+ !outcome.sha &&
2593
+ state.head === stateRef(state, REMOTE_MAIN) &&
2594
+ !syncPending(ctx);
2595
+ if (quiet)
2596
+ return { ...outcome, sync: null };
2597
+ untouched = false;
2598
+ const after = await syncAfterCommit(ctx, syncModeFor(ctx, (opts.paths?.length ?? 0) > 0));
2599
+ await packAfterCommit(ctx, reason);
2600
+ return { ...outcome, ...after };
2601
+ }
2602
+ finally {
2603
+ if (!leave)
2604
+ refreshSnapshot(ctx, false, { mirror, state: untouched ? state : undefined });
2605
+ }
1274
2606
  });
1275
2607
  }
1276
2608
  /**
@@ -1280,12 +2612,21 @@ export async function cloudCommit(dir, opts, deps) {
1280
2612
  export async function cloudSync(dir, deps) {
1281
2613
  const ctx = contextFor(dir, deps);
1282
2614
  requireAttached(ctx, 'git sync');
2615
+ // Ghost pokes this route after each mirror run: always asked (before the lock).
2616
+ const mirror = await askMirrorIfDue(ctx, { always: true });
1283
2617
  return withDeckLock(ctx, async () => {
1284
- if (deckBusy(ctx)) {
1285
- markSyncPending(ctx);
1286
- return { merge: 'deferred', pushed: false };
2618
+ // History missing: the background rehydrate (which takes this lock only at its end).
2619
+ requireHistory(ctx, { leave: false });
2620
+ try {
2621
+ if (deckBusy(ctx)) {
2622
+ markSyncPending(ctx);
2623
+ return { merge: 'deferred', pushed: false };
2624
+ }
2625
+ return await syncLocked(ctx, { commitFirst: true, mode: 'full' });
2626
+ }
2627
+ finally {
2628
+ refreshSnapshot(ctx, false, { mirror });
1287
2629
  }
1288
- return syncLocked(ctx, { commitFirst: true, mode: 'full' });
1289
2630
  });
1290
2631
  }
1291
2632
  /**
@@ -1296,31 +2637,42 @@ export async function cloudSync(dir, deps) {
1296
2637
  export async function cloudRestore(dir, target, deps) {
1297
2638
  const ctx = contextFor(dir, deps);
1298
2639
  requireAttached(ctx, 'restore-version');
2640
+ const mirror = await askMirrorIfDue(ctx, { always: false });
1299
2641
  return withDeckLock(ctx, async () => {
1300
- requireMainBranch(ctx);
1301
- const sha = revParse(ctx, target);
1302
- if (!sha || !ok(ctx, ['merge-base', '--is-ancestor', sha, 'HEAD'])) {
1303
- throw new CloudGitError(`No such version in this deck's history: ${target}`);
1304
- }
1305
- // Rewriting the files under a task agent at work would mix its edits into the old version:
1306
- // asked before anything is done, and again right before the files are rewritten.
1307
- const refuseIfBusy = () => {
1308
- if (deckBusy(ctx)) {
1309
- throw new CloudGitError('Task agents are working in this deck, so it was not restored. Restore it once they finish.');
1310
- }
1311
- };
1312
- refuseIfBusy();
1313
- await commitLocked(ctx, { reason: 'manual', message: 'Work in progress before restoring a version' });
1314
- const subject = must(ctx, ['log', '-1', '--format=%s', sha]).trim();
1315
- refuseIfBusy();
1316
- must(ctx, ['read-tree', '-u', '--reset', sha]);
1317
- const outcome = await commitLocked(ctx, {
1318
- reason: 'manual',
1319
- message: `Restore version ${sha.slice(0, 7)}${subject ? `: ${subject}` : ''}`,
1320
- });
1321
- return { ...outcome, ...(await syncAfterCommit(ctx, syncModeFor(ctx, false))) };
2642
+ requireHistory(ctx, { leave: false });
2643
+ try {
2644
+ return await restoreLocked(ctx, target);
2645
+ }
2646
+ finally {
2647
+ refreshSnapshot(ctx, false, { mirror });
2648
+ }
1322
2649
  });
1323
2650
  }
2651
+ async function restoreLocked(ctx, target) {
2652
+ requireMainBranch(ctx);
2653
+ const sha = revParse(ctx, target);
2654
+ if (!sha || !ok(ctx, ['merge-base', '--is-ancestor', sha, 'HEAD'])) {
2655
+ throw new CloudGitError(`No such version in this deck's history: ${target}`);
2656
+ }
2657
+ // Rewriting the files under a task agent at work would mix its edits into the old version:
2658
+ // asked before anything is done, and again right before the files are rewritten.
2659
+ const refuseIfBusy = () => {
2660
+ const busy = ctx.deps.env[AGENT_ROLE_ENV] === 'router' ? deckTasksBusy(ctx) : deckBusy(ctx);
2661
+ if (busy) {
2662
+ throw new CloudGitError('Task agents are working in this deck, so it was not restored. Restore it once they finish.');
2663
+ }
2664
+ };
2665
+ refuseIfBusy();
2666
+ await commitLocked(ctx, { reason: 'manual', message: 'Work in progress before restoring a version' });
2667
+ const subject = must(ctx, ['log', '-1', '--format=%s', sha]).trim();
2668
+ refuseIfBusy();
2669
+ must(ctx, ['read-tree', '-u', '--reset', sha]);
2670
+ const outcome = await commitLocked(ctx, {
2671
+ reason: 'manual',
2672
+ message: `Restore version ${sha.slice(0, 7)}${subject ? `: ${subject}` : ''}`,
2673
+ });
2674
+ return { ...outcome, ...(await syncAfterCommit(ctx, syncModeFor(ctx, false))) };
2675
+ }
1324
2676
  // --- attach -----------------------------------------------------------------
1325
2677
  const CASTLE_REMOTE_RE = /^https:\/\/([a-z0-9.-]+)\/([A-Za-z0-9_-]{1,64})\.git$/;
1326
2678
  function parseRemoteUrl(url) {
@@ -1363,6 +2715,10 @@ function ensureOwnRepo(ctx) {
1363
2715
  if (stat && !stat.isDirectory()) {
1364
2716
  throw new CloudGitError(`${dotGit} is not a directory (a gitdir file or link); refusing to attach.`);
1365
2717
  }
2718
+ // A restored deck's .git lacks its objects directory; with it back, a failure below means a
2719
+ // repo git really cannot read, not one waiting to be rehydrated.
2720
+ if (stat)
2721
+ repairGitSkeleton(ctx.dir);
1366
2722
  const top = run(ctx, ['rev-parse', '--show-toplevel']);
1367
2723
  if (stat) {
1368
2724
  if (top.status !== 0)
@@ -1400,6 +2756,12 @@ function forgetOtherDecksRemote(ctx, deckId) {
1400
2756
  run(ctx, ['config', '--local', '--unset-all', key]);
1401
2757
  }
1402
2758
  fs.rmSync(mergeStatePath(ctx.dir), { force: true });
2759
+ // The other deck's mirror floor says nothing about what this deck's mirror has.
2760
+ for (const ref of [MIRRORED_REF, INTEGRATED_REF]) {
2761
+ const sha = refValue(ctx, ref);
2762
+ if (sha)
2763
+ run(ctx, ['update-ref', '-d', ref, sha]);
2764
+ }
1403
2765
  return other;
1404
2766
  }
1405
2767
  // Local main, whatever the repo started on: an unborn HEAD is pointed at main; a born one on
@@ -1493,9 +2855,12 @@ export async function cloudAttach(dir, remoteUrl, deps) {
1493
2855
  must(ctx, ['--version']);
1494
2856
  const repo = ensureOwnRepo(ctx);
1495
2857
  const original = forgetOtherDecksRemote(ctx, deckId);
1496
- if (original)
2858
+ if (original) {
1497
2859
  deps.warn(`This repo was attached to deck ${original}'s remote (a copied deck); attaching it to ${deckId}'s instead.`);
1498
- ensureMainBranch(ctx);
2860
+ // Its history is the other deck's: not rebuilt from there, and not "recovered" either.
2861
+ if (historyMissing(ctx).length > 0)
2862
+ dropForeignHistory(ctx, original);
2863
+ }
1499
2864
  setCastleRemote(ctx, remoteUrl);
1500
2865
  const stripped = stripEmptyCredentialHelpers(ctx);
1501
2866
  if (stripped.length)
@@ -1508,12 +2873,23 @@ export async function cloudAttach(dir, remoteUrl, deps) {
1508
2873
  // The base in conflict markers is what lets the agent see what each side changed.
1509
2874
  must(ctx, ['config', '--local', 'merge.conflictStyle', 'diff3']);
1510
2875
  return withDeckLock(ctx, async () => {
1511
- const outcome = await firstSync(ctx, repo);
1512
- // Marked attached only once the repo shares history with the remote: a deck whose
1513
- // first fetch failed must not start a local history of its own, which the next attach
1514
- // could not merge. The next open retries the whole attach.
1515
- must(ctx, ['config', '--local', 'castle.cloud', 'true']);
1516
- return outcome;
2876
+ // A cold resume's repo has refs but no objects: the rehydrate runs in the background, and
2877
+ // this attach stops at once (castle-www runs it in the background on open).
2878
+ requireHistory(ctx, { leave: false });
2879
+ try {
2880
+ ensureMainBranch(ctx);
2881
+ const outcome = await firstSync(ctx, repo);
2882
+ // Marked attached only once the repo shares history with the remote: a deck whose
2883
+ // first fetch failed must not start a local history of its own, which the next attach
2884
+ // could not merge. The next open retries the whole attach.
2885
+ must(ctx, ['config', '--local', 'castle.cloud', 'true']);
2886
+ return outcome;
2887
+ }
2888
+ finally {
2889
+ // Only for a deck attach has set up: the key file lets the host leave its objects out.
2890
+ if (localConfig(ctx, 'castle.cloud') === 'true')
2891
+ refreshSnapshot(ctx, false);
2892
+ }
1517
2893
  });
1518
2894
  }
1519
2895
  // The seed commit an attach made for an empty remote, until it is pushed. Should the push
@@ -1535,6 +2911,7 @@ function undoUnpushedSeed(ctx) {
1535
2911
  }
1536
2912
  async function firstSync(ctx, repo) {
1537
2913
  undoUnpushedSeed(ctx);
2914
+ await commitRecoveredRoot(ctx);
1538
2915
  const remote = fetchRemote(ctx);
1539
2916
  const head = revParse(ctx, 'HEAD');
1540
2917
  if (!remote) {
@@ -1654,6 +3031,7 @@ function readGitLog(ctx, from, limit) {
1654
3031
  * refresh never holds the index lock a commit needs.
1655
3032
  */
1656
3033
  export async function gitVersionHistory(dir, env = process.env) {
3034
+ repairGitSkeleton(dir);
1657
3035
  const git = async (args) => {
1658
3036
  const result = await runGitAsync(['--no-optional-locks', ...args], dir, env);
1659
3037
  if (result.status !== 0)
@@ -1661,6 +3039,10 @@ export async function gitVersionHistory(dir, env = process.env) {
1661
3039
  return result.stdout;
1662
3040
  };
1663
3041
  const head = await runGitAsync(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], dir, env);
3042
+ // HEAD names a commit that is not here: a cold resume whose history is being rehydrated.
3043
+ if (head.status !== 0 && (await runGitAsync(['rev-parse', '--verify', '--quiet', 'HEAD'], dir, env)).status === 0) {
3044
+ return { versions: [], pending: [], loading: true };
3045
+ }
1664
3046
  const versions = head.status === 0 ? parseGitLog(await git(logArgs('HEAD', LOG_LIMIT))) : [];
1665
3047
  const status = await git(['status', '--porcelain=v1', '-z', '--untracked-files=all']);
1666
3048
  return { versions, pending: parseStatus(status) };
@@ -1669,7 +3051,12 @@ export async function gitVersionHistory(dir, env = process.env) {
1669
3051
  // agent working out what recent work did.
1670
3052
  export function printGitLog(dir, from, git = cloudGitRunner()) {
1671
3053
  const ctx = { dir, deps: { git }, startedAt: 0 };
3054
+ repairGitSkeleton(dir);
1672
3055
  if (!revParse(ctx, from ?? 'HEAD')) {
3056
+ if (!from && refValue(ctx, 'HEAD')) {
3057
+ console.log("History is loading: this deck's git history is being rebuilt after the sandbox restarted. Try again in a minute.");
3058
+ return;
3059
+ }
1673
3060
  console.log(from ? `No such version: ${from}` : 'No versions yet.');
1674
3061
  return;
1675
3062
  }