@awebai/oats 0.67.1 → 0.68.0

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 (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -23,7 +23,10 @@
23
23
  * rollback journal: should any step fail, everything already placed is undone and the
24
24
  * previous AGENTS.md / instance.json restored before a named error (E_MATERIALIZE_HOME)
25
25
  * propagates. A second materialization racing on the same home surfaces as
26
- * E_MATERIALIZE_HOME { why: "busy" }, never a raw ENOTEMPTY.
26
+ * E_MATERIALIZE_HOME { why: "busy" }, never a raw ENOTEMPTY. stageMaterialize exposes
27
+ * that same composer before commit, including complete-root replacement for stopped
28
+ * homes. Its durable rename journal can finish forward after provider adoption; ordinary
29
+ * materialize calls continue to roll back a failed commit and discard staging.
27
30
  *
28
31
  * SOURCES. A module is fetched from its repository at `from.commit` at the capability
29
32
  * directory the RESOLVER recorded (`module.dir`: the manifest-listed directory — for a
@@ -186,15 +189,20 @@ function moduleSource(module, { lock, catalog, remote }) {
186
189
  /* ───────────────────────────── copying ─────────────────────────────── */
187
190
 
188
191
  /** Full copy of a fetched tree: regular files and directories only, exec bit preserved as 0o755 / 0o644. */
189
- function copyTree(src, dest, shownRoot) {
192
+ function copyTree(src, dest, shownRoot, allowAliases = false, root = src) {
190
193
  const st = lstatSync(src);
191
194
  if (st.isSymbolicLink()) throw fail("E_REMOTE_TREE_UNSAFE", `${shownRoot} is a symlink`, { path: shownRoot, why: "symlink" });
192
195
  if (!st.isDirectory()) throw fail("E_MATERIALIZE_RESOLUTION", `${shownRoot} is not a directory`, { path: shownRoot });
193
196
  mkdirSync(dest, { recursive: true, mode: 0o755 });
194
197
  for (const name of readdirSync(src).sort()) {
195
198
  const from = join(src, name), to = join(dest, name), shown = `${shownRoot}/${name}`, s = lstatSync(from);
196
- if (s.isSymbolicLink()) throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is a symlink`, { path: shown, why: "symlink" });
197
- if (s.isDirectory()) { copyTree(from, to, shown); continue; }
199
+ if (s.isSymbolicLink()) {
200
+ if (allowAliases && defaultRemote.OATS_ALIAS_SYMLINK(relative(root, from).split(sep).join("/")) && readlinkSync(from) === "AGENTS.md") {
201
+ symlinkSync("AGENTS.md", to); continue;
202
+ }
203
+ throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is a symlink`, { path: shown, why: "symlink" });
204
+ }
205
+ if (s.isDirectory()) { copyTree(from, to, shown, allowAliases, root); continue; }
198
206
  if (!s.isFile()) throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is not a regular file`, { path: shown, why: "device" });
199
207
  copyFileSync(from, to);
200
208
  chmodSync(to, (s.mode & 0o111) ? 0o755 : 0o644);
@@ -366,8 +374,29 @@ function ensureOatsDir(home) {
366
374
  * blocks pre-rendered blocks [{ source, file, content }] placed BEFORE the capability injects
367
375
  * (the kernel's own kernel:… and work-mode:… blocks, composed by core.mjs)
368
376
  * now() ISO timestamp source (tests)
377
+ *
378
+ * stageMaterialize adds `replace` (complete roots), `staging` (explicit scratch
379
+ * directory), `existingModules` (name → frozen source path), and `instanceJson`
380
+ * (derived metadata transform). Its commit({preserveOnFailure:true}) retains
381
+ * forward progress and can be reopened with {staging, resume:true}. Add
382
+ * retainStaging:true until the caller has durably recorded its remaining lifecycle steps.
369
383
  */
370
384
  export async function materialize(resolution, home, options = {}) {
385
+ const transaction = await stageMaterialize(resolution, home, options);
386
+ return transaction.commit();
387
+ }
388
+
389
+ /** Build the same composition as spawn without publishing it. Replacement transactions
390
+ * swap complete module/skill roots; a caller holds the lifecycle claim while using them.
391
+ * `staging` may be outside the home for a read-only preview. `resume` reopens a staged
392
+ * transaction after an interrupted forward-only commit; no resolution or fetch is needed.
393
+ * `existingModules` names verified frozen copies to retain instead of fetching them.
394
+ * `instanceJson(merged, outcome)` supplies the caller's derived metadata; updateInstance
395
+ * can subsequently record provider hook results before commit. rollback() restores
396
+ * a retained swap when no provider hook has adopted the new version.
397
+ */
398
+ export async function stageMaterialize(resolution, home, options = {}) {
399
+ if (options.resume) return resumeMaterialization(home, options.staging);
371
400
  assertResolution(resolution);
372
401
  const homeAbs = assertHome(home);
373
402
  const remote = options.remote ?? defaultRemote;
@@ -380,7 +409,12 @@ export async function materialize(resolution, home, options = {}) {
380
409
  const { lock, catalog } = options;
381
410
 
382
411
  // Everything that can be decided without touching the network or the disk, first.
383
- const sources = resolution.modules.map((m) => ({ module: m, source: moduleSource(m, { lock, catalog, remote }) }));
412
+ const sources = resolution.modules.map((m) => {
413
+ const existing = Object.hasOwn(options.existingModules ?? {}, m.name) ? options.existingModules[m.name] : undefined;
414
+ return { module: m, existing,
415
+ source: existing ? { commit: m.from.commit, key: m.from.repoKey } : moduleSource(m, { lock, catalog, remote }),
416
+ };
417
+ });
384
418
  const body = soulBody(homeAbs, options);
385
419
  const instanceFile = join(homeAbs, "instance.json");
386
420
  const previous = readInstanceJson(instanceFile);
@@ -398,13 +432,13 @@ export async function materialize(resolution, home, options = {}) {
398
432
  const target = join(modulesRoot, module.name);
399
433
  let st = null;
400
434
  try { st = lstatSync(target); } catch {}
401
- if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
435
+ if (st && !options.replace) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
402
436
  }
403
437
  for (const owner of skillOwners.values()) {
404
438
  const name = owner.name, target = join(skillsRoot, name);
405
439
  let st = null;
406
440
  try { st = lstatSync(target); } catch {}
407
- if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
441
+ if (st && !options.replace) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
408
442
  }
409
443
  for (const p of parents) {
410
444
  let st = null;
@@ -419,33 +453,39 @@ export async function materialize(resolution, home, options = {}) {
419
453
  };
420
454
  assertHomeShape();
421
455
 
422
- const oats = ensureOatsDir(homeAbs);
456
+ const oats = options.staging ? { dir: join(homeAbs, ".oats"), created: false } : ensureOatsDir(homeAbs);
423
457
  // Unique per call: two materializations of one home in one process (or across processes) never share staging.
424
- const staging = join(oats.dir, `.staging-${process.pid}-${randomBytes(6).toString("hex")}`);
458
+ const staging = options.staging ? resolve(options.staging) : join(oats.dir, `.staging-${process.pid}-${randomBytes(6).toString("hex")}`);
459
+ assertStagingPath(staging, homeAbs);
460
+ if (linkPresent(staging)) throw fail("E_MATERIALIZE_HOME", `staging directory ${staging} already exists; resume it explicitly or choose another path`, { path: staging, why: "busy" });
461
+ let stagingOwned = false;
425
462
  const discard = () => {
426
- try { rmSync(staging, { recursive: true, force: true }); } catch { /* an unremovable staging dir must not mask the original error */ }
463
+ try { if (stagingOwned) rmSync(staging, { recursive: true, force: true }); } catch { /* an unremovable staging dir must not mask the original error */ }
427
464
  if (oats.created) { try { rmdirSync(oats.dir); } catch { /* something else appeared; leave it */ } }
428
465
  };
429
- /** A real directory at `p` (mkdir without following a symlink; EEXIST on a non-directory → refusal). */
430
- const ensureDir = (p) => {
431
- try { mkdirSync(p, { mode: 0o755 }); }
432
- catch (e) {
433
- if (e?.code !== "EEXIST") throw e;
434
- if (!lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { home: homeAbs, path: p, why: "not-a-directory" });
435
- }
436
- };
437
466
 
438
467
  let outcome;
439
468
  try {
440
- mkdirSync(join(staging, "modules"), { recursive: true, mode: 0o755 });
441
- mkdirSync(join(staging, "skills"), { recursive: true, mode: 0o755 });
469
+ try { mkdirSync(staging, { mode: 0o755 }); }
470
+ catch (e) {
471
+ if (e?.code === "EEXIST") throw fail("E_MATERIALIZE_HOME", `${staging} appeared while materializing`, { path: staging, why: "busy" });
472
+ throw e;
473
+ }
474
+ stagingOwned = true;
475
+ mkdirSync(join(staging, "modules"), { mode: 0o755 });
476
+ mkdirSync(join(staging, "skills"), { mode: 0o755 });
442
477
 
443
478
  const moduleRows = [], skillRows = [], capabilityBlocks = [], recorded = {};
444
- for (const { module, source } of sources) {
479
+ for (const { module, source, existing } of sources) {
445
480
  const stagedModule = join(staging, "modules", module.name);
446
481
  const finalModule = join(modulesRoot, module.name);
447
482
  let fetched;
448
- try { fetched = await fetch(source.ref, source.commit, source.dir, stagedModule, { ...(options.remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK }); }
483
+ try {
484
+ if (existing) {
485
+ copyTree(existing, stagedModule, module.name, true);
486
+ fetched = { digest: remote.contentDigest(stagedModule, { allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK }) };
487
+ } else fetched = await fetch(source.ref, source.commit, source.dir, stagedModule, { ...(options.remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
488
+ }
449
489
  catch (e) {
450
490
  if (e?.code === "E_REMOTE_PATH_MISSING") {
451
491
  throw fail("E_CAPABILITY_MISSING", `module ${module.name}: ${source.dir} is not present in ${source.key}@${source.commit.slice(0, 12)}`,
@@ -468,9 +508,10 @@ export async function materialize(resolution, home, options = {}) {
468
508
  throw fail("E_MATERIALIZE_INTEGRITY", `module ${module.name}: the copy digests ${digest} but the fetch reported ${fetched.digest}`,
469
509
  { module: module.name, repoKey: source.key, commit: source.commit, expected: fetched.digest, actual: digest, why: "copy" });
470
510
  }
471
- if (module.digest && module.digest !== digest) {
472
- throw fail("E_MATERIALIZE_INTEGRITY", `module ${module.name}: content digest ${digest} does not match the resolution's ${module.digest}`,
473
- { module: module.name, repoKey: source.key, commit: source.commit, expected: module.digest, actual: digest, why: "resolution" });
511
+ const expectedDigest = module.digest ?? (existing ? previous.modules?.[module.name]?.digest : null);
512
+ if (expectedDigest && expectedDigest !== digest) {
513
+ throw fail("E_MATERIALIZE_INTEGRITY", `module ${module.name}: content digest ${digest} does not match the recorded ${expectedDigest}`,
514
+ { module: module.name, repoKey: source.key, commit: source.commit, expected: expectedDigest, actual: digest, why: "resolution" });
474
515
  }
475
516
 
476
517
  for (const skill of moduleSkills(resolution, module, stagedModule)) {
@@ -498,7 +539,8 @@ export async function materialize(resolution, home, options = {}) {
498
539
 
499
540
  const at = now();
500
541
  const from = clone(module.from);
501
- recorded[module.name] = { from, commit: source.commit, digest, materializedAt: at };
542
+ recorded[module.name] = existing && previous.modules?.[module.name]?.digest === digest && previous.modules[module.name].commit === source.commit
543
+ ? clone(previous.modules[module.name]) : { from, commit: source.commit, digest, materializedAt: at };
502
544
  moduleRows.push({ name: module.name, from, commit: source.commit, digest, files: fetched.files ?? null, bytes: fetched.bytes ?? null, path: finalModule, materializedAt: at });
503
545
  }
504
546
 
@@ -511,65 +553,170 @@ export async function materialize(resolution, home, options = {}) {
511
553
  const agentsText = renderInstructionText(body.text, blocks);
512
554
  writeFileSync(join(staging, "AGENTS.md"), agentsText, { mode: 0o644 });
513
555
 
514
- const merged = { ...previous, modules: recorded, providers: clone(resolution.payloads ?? {}) };
556
+ let merged = { ...previous, modules: recorded, providers: clone(resolution.payloads ?? {}) };
515
557
  if (typeof resolution.revision === "string" && resolution.revision) merged.resolutionRevision = resolution.revision;
558
+ outcome = { modules: moduleRows, skills: skillRows, agentsMd: join(homeAbs, "AGENTS.md"), instanceJson: merged, blocks };
559
+ if (typeof options.instanceJson === "function") merged = options.instanceJson(merged, outcome);
560
+ if (!plainObject(merged)) throw fail("E_MATERIALIZE_RESOLUTION", "options.instanceJson must return an object");
561
+ outcome.instanceJson = merged;
516
562
  writeFileSync(join(staging, "instance.json"), JSON.stringify(merged, null, 2) + "\n", { mode: 0o644 });
563
+ const state = { api: 1, home: homeAbs, replace: options.replace === true, outcome, operations: [], initialParents: [".claude", SKILLS_DIR, ".agents", MODULES_DIR].filter(p => linkPresent(join(homeAbs, p))) };
564
+ saveMaterialization(staging, state);
565
+ return materializationTransaction(staging, state, { assertHomeShape, discard });
566
+ } catch (error) {
567
+ discard();
568
+ throw error;
569
+ }
570
+ }
517
571
 
518
- // ── commit: re-check the home (TOCTOU), then a short sequence of renames with a rollback journal ──
519
- assertHomeShape();
520
- const undo = []; // LIFO: () => void
521
- const backupDir = join(staging, "previous");
522
- mkdirSync(backupDir, { mode: 0o755 });
523
- const swapIn = (src, dest, label) => {
524
- // Preserve whatever was at dest (file or symlink) in staging so a later failure can restore it.
525
- let had = false;
526
- try { lstatSync(dest); had = true; } catch {}
527
- if (had) { renameSync(dest, join(backupDir, label)); undo.push(() => renameSync(join(backupDir, label), dest)); }
528
- renameSync(src, dest);
529
- undo.push(() => rmSync(dest, { recursive: true, force: true }));
530
- };
531
- const placeDir = (src, dest) => {
532
- try { renameSync(src, dest); }
533
- catch (e) {
534
- if (e?.code === "EEXIST" || e?.code === "ENOTEMPTY" || e?.code === "EISDIR") {
535
- throw fail("E_MATERIALIZE_HOME", `${dest} appeared while materializing — another materialization of this home is in flight, or the home changed under us`, { home: homeAbs, path: dest, why: "busy" });
536
- }
537
- throw e;
538
- }
539
- undo.push(() => rmSync(dest, { recursive: true, force: true }));
540
- };
541
- const mkdirTracked = (p) => {
542
- let existed = true;
543
- try { lstatSync(p); } catch { existed = false; }
544
- ensureDir(p);
545
- if (!existed) undo.push(() => { try { rmdirSync(p); } catch { /* not empty: someone else's */ } });
546
- };
572
+ const TRANSACTION_FILE = ".materialize-transaction.json";
573
+
574
+ /** Refuse path aliases before creating or reopening staging. Staging cannot cover the
575
+ * home itself or any published composition path. Ancestors inside the home must be
576
+ * real directories; system ancestors such as macOS /tmp may be directory aliases. */
577
+ function assertStagingPath(staging, home) {
578
+ if (!isAbsolute(staging) || staging === home || relative(staging, home).split(sep)[0] !== "..") {
579
+ throw fail("E_MATERIALIZE_HOME", `unsafe staging directory ${staging}`, { path: staging });
580
+ }
581
+ if ([".oats", ".agents", ".claude", "AGENTS.md", "instance.json", "CLAUDE.md"].some(p => join(home, p) === staging)) throw fail("E_MATERIALIZE_HOME", `staging directory overlaps the home composition: ${staging}`, { path: staging });
582
+ for (const published of [join(home, MODULES_DIR), join(home, SKILLS_DIR)]) {
583
+ const rel = relative(published, staging);
584
+ if (!rel || (!rel.startsWith(`..${sep}`) && rel !== "..")) throw fail("E_MATERIALIZE_HOME", `staging directory is inside ${published}`, { path: staging });
585
+ }
586
+ let at = resolve(staging, "..");
587
+ const insideHome = !relative(home, staging).startsWith(`..${sep}`);
588
+ while (insideHome && at !== home) {
589
+ if (linkPresent(at) && !lstatSync(at).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${at} exists and is not a directory`, { path: at });
590
+ const parent = resolve(at, "..");
591
+ if (parent === at) break;
592
+ at = parent;
593
+ }
594
+ }
595
+
596
+ function saveMaterialization(staging, state) {
597
+ const file = join(staging, TRANSACTION_FILE), temp = `${file}.tmp`;
598
+ writeFileSync(temp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
599
+ renameSync(temp, file);
600
+ }
601
+
602
+ function resumeMaterialization(home, stagingPath) {
603
+ const homeAbs = assertHome(home);
604
+ if (typeof stagingPath !== "string" || !isAbsolute(stagingPath)) throw fail("E_MATERIALIZE_HOME", "resuming materialization requires an absolute staging path");
605
+ const staging = resolve(stagingPath);
606
+ assertStagingPath(staging, homeAbs);
607
+ if (!lstatSync(staging).isDirectory() || !lstatSync(join(staging, TRANSACTION_FILE)).isFile()) throw fail("E_MATERIALIZE_HOME", `invalid materialization staging directory ${staging}`);
608
+ const state = readInstanceJson(join(staging, TRANSACTION_FILE));
609
+ if (state.api !== 1 || state.home !== homeAbs || typeof state.replace !== "boolean" || !plainObject(state.outcome) || !Array.isArray(state.outcome.modules) || !Array.isArray(state.outcome.skills) || !Array.isArray(state.operations)) throw fail("E_MATERIALIZE_HOME", `invalid materialization transaction in ${staging}`);
610
+ return materializationTransaction(staging, state);
611
+ }
612
+
613
+ /** A durable intent before each rename makes an interrupted swap distinguishable from
614
+ * a pending one. Forward-only failures keep both copies and retry the remaining moves;
615
+ * ordinary spawn failures reverse the same journal and discard staging. */
616
+ function materializationTransaction(staging, state, callbacks = {}) {
617
+ const home = state.home, outcome = state.outcome;
618
+ const discard = callbacks.discard ?? (() => { try { rmSync(staging, { recursive: true, force: true }); } catch { /* cleanup must not turn success into rollback */ } });
619
+ let committed = false;
620
+ const operations = () => state.replace
621
+ ? [{ label: "modules", dest: join(home, MODULES_DIR) }, { label: "skills", dest: join(home, SKILLS_DIR) }, { label: "AGENTS.md", dest: join(home, "AGENTS.md") }, { label: "instance.json", dest: join(home, "instance.json") }]
622
+ : [...outcome.modules.map(m => ({ label: `modules/${safeName(m.name)}`, dest: join(home, MODULES_DIR, m.name) })),
623
+ ...outcome.skills.map(s => ({ label: `skills/${safeName(s.name)}`, dest: join(home, SKILLS_DIR, s.name) })),
624
+ { label: "AGENTS.md", dest: join(home, "AGENTS.md") }, { label: "instance.json", dest: join(home, "instance.json") }];
625
+ const allowedLabels = new Set(operations().map(op => op.label));
626
+ if (state.operations.some(op => !plainObject(op) || !allowedLabels.has(op.label) || typeof op.had !== "boolean" || !["pending", "backed", "placed"].includes(op.phase)) ||
627
+ (state.aliases !== undefined && (!Array.isArray(state.aliases) || state.aliases.some(alias => !["CLAUDE.md", ".claude/skills"].includes(alias))))) {
628
+ throw fail("E_MATERIALIZE_HOME", `invalid materialization journal in ${staging}`, { path: staging });
629
+ }
630
+ const ensureDir = (p) => {
631
+ if (linkPresent(p)) {
632
+ if (!lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { path: p });
633
+ } else mkdirSync(p, { mode: 0o755 });
634
+ };
635
+ const checkParents = () => {
636
+ for (const p of [join(home, ".oats"), join(home, ".agents"), join(home, ".claude")]) ensureDir(p);
637
+ for (const p of [join(home, MODULES_DIR), join(home, SKILLS_DIR)]) if (linkPresent(p) && !lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { path: p });
638
+ if (!state.replace) { ensureDir(join(home, MODULES_DIR)); ensureDir(join(home, SKILLS_DIR)); }
639
+ };
640
+ const safeBackup = (label) => join(staging, "previous", ...label.split("/"));
641
+ const safeSource = (label) => join(staging, ...label.split("/"));
642
+ const updateInstance = (json) => {
643
+ if (!plainObject(json) || state.operations.length || committed) throw fail("E_MATERIALIZE_HOME", "instance metadata can only be updated before the materialization swap");
644
+ outcome.instanceJson = clone(json);
645
+ writeFileSync(join(staging, "instance.json"), JSON.stringify(json, null, 2) + "\n", { mode: 0o644 });
646
+ saveMaterialization(staging, state);
647
+ };
648
+ const rollback = ({ suppressErrors = false } = {}) => {
649
+ if (!linkPresent(staging)) throw fail("E_MATERIALIZE_HOME", "materialization staging is gone; rollback requires retainStaging:true", { path: staging });
650
+ const failures = [];
651
+ for (const alias of state.aliases ?? []) {
652
+ try { rmSync(join(home, alias), { force: true }); } catch (e) { failures.push(e.message); }
653
+ }
654
+ for (const op of operations().reverse()) {
655
+ const saved = state.operations.find(row => row.label === op.label);
656
+ if (!saved) continue;
657
+ const src = safeSource(op.label), backup = safeBackup(op.label);
658
+ try {
659
+ if (!linkPresent(src) && linkPresent(op.dest)) { mkdirSync(resolve(src, ".."), { recursive: true }); renameSync(op.dest, src); }
660
+ if (linkPresent(backup)) renameSync(backup, op.dest);
661
+ } catch (e) { failures.push(e.message); }
662
+ }
663
+ // Only remove parents created by this materialization, and only if empty.
664
+ for (const rel of [".claude", SKILLS_DIR, ".agents", MODULES_DIR]) {
665
+ try { if (!state.initialParents?.includes(rel)) rmdirSync(join(home, rel)); } catch {}
666
+ }
667
+ if (!failures.length) discard();
668
+ else if (!suppressErrors) throw fail("E_MATERIALIZE_HOME", `cannot fully roll back materialization; staging retained at ${staging}: ${failures.join("; ")}`, { path: staging, why: "rollback" });
669
+ committed = false;
670
+ };
671
+ const commit = ({ preserveOnFailure = false, retainStaging = false } = {}) => {
672
+ if (committed) return outcome;
547
673
  try {
548
- for (const p of [join(homeAbs, ".oats"), modulesRoot, join(homeAbs, ".agents"), skillsRoot, join(homeAbs, ".claude")]) mkdirTracked(p);
549
- for (const { module } of sources) placeDir(join(staging, "modules", module.name), join(modulesRoot, module.name));
550
- for (const row of skillRows) placeDir(join(staging, "skills", row.name), row.path);
551
- swapIn(join(staging, "AGENTS.md"), join(homeAbs, "AGENTS.md"), "AGENTS.md");
552
- swapIn(join(staging, "instance.json"), instanceFile, "instance.json");
553
- // Aliases (relative symlinks), only when absent — the canonical-plus-alias construction stays; inside the transaction.
554
- const claudeMd = join(homeAbs, "CLAUDE.md");
555
- if (!linkPresent(claudeMd)) { symlinkSync("AGENTS.md", claudeMd); undo.push(() => rmSync(claudeMd, { force: true })); }
556
- const claudeSkills = join(homeAbs, ".claude", "skills");
557
- if (!linkPresent(claudeSkills)) { symlinkSync(join("..", ".agents", "skills"), claudeSkills); undo.push(() => rmSync(claudeSkills, { force: true })); }
558
- } catch (e) {
559
- for (const step of undo.reverse()) { try { step(); } catch { /* best effort: the original error is what matters */ } }
560
- if (e?.code === "EACCES" || e?.code === "EPERM" || e?.code === "EROFS" || e?.code === "EISDIR" || e?.code === "ENOTDIR") {
561
- throw fail("E_MATERIALIZE_HOME", `cannot write the instance home ${homeAbs}: ${e.message}`, { home: homeAbs, why: "unwritable", cause: e.code });
674
+ // Spawn retains its original pre-commit race checks. A resumed replacement
675
+ // may already have published roots, so only its parent shape is checked.
676
+ if (!state.operations.length) callbacks.assertHomeShape?.();
677
+ checkParents();
678
+ for (const op of operations()) {
679
+ let saved = state.operations.find(row => row.label === op.label);
680
+ const src = safeSource(op.label), backup = safeBackup(op.label);
681
+ if (!saved) {
682
+ saved = { label: op.label, had: linkPresent(op.dest), phase: "pending" };
683
+ if (!state.replace && (op.label.startsWith("modules/") || op.label.startsWith("skills/")) && saved.had) throw fail("E_MATERIALIZE_HOME", `${op.dest} appeared while materializing`, { path: op.dest, why: "busy" });
684
+ state.operations.push(saved); saveMaterialization(staging, state);
685
+ }
686
+ if (saved.phase === "pending") {
687
+ if (saved.had && !linkPresent(backup)) {
688
+ mkdirSync(resolve(backup, ".."), { recursive: true });
689
+ renameSync(op.dest, backup);
690
+ }
691
+ saved.phase = "backed"; saveMaterialization(staging, state);
692
+ }
693
+ if (saved.phase === "backed") {
694
+ if (linkPresent(src)) {
695
+ if (linkPresent(op.dest)) throw fail("E_MATERIALIZE_HOME", `${op.dest} appeared while materializing`, { path: op.dest, why: "busy" });
696
+ renameSync(src, op.dest);
697
+ }
698
+ else if (!linkPresent(op.dest)) throw fail("E_MATERIALIZE_HOME", `staged materialization is missing ${src}`, { path: src });
699
+ saved.phase = "placed"; saveMaterialization(staging, state);
700
+ }
562
701
  }
563
- throw e;
702
+ const claudeMd = join(home, "CLAUDE.md"), claudeSkills = join(home, ".claude", "skills");
703
+ if (!linkPresent(claudeMd)) { symlinkSync("AGENTS.md", claudeMd); state.aliases = [...(state.aliases ?? []), "CLAUDE.md"]; saveMaterialization(staging, state); }
704
+ if (!linkPresent(claudeSkills)) { symlinkSync(join("..", ".agents", "skills"), claudeSkills); state.aliases = [...(state.aliases ?? []), ".claude/skills"]; saveMaterialization(staging, state); }
705
+ committed = true;
706
+ if (!retainStaging) discard();
707
+ return outcome;
708
+ } catch (error) {
709
+ if (!preserveOnFailure) rollback({ suppressErrors: true });
710
+ if (["EACCES", "EPERM", "EROFS", "EISDIR", "ENOTDIR"].includes(error?.code)) throw fail("E_MATERIALIZE_HOME", `cannot write the instance home ${home}: ${error.message}`, { home, why: "unwritable", cause: error.code });
711
+ throw error;
564
712
  }
565
- discard();
713
+ };
714
+ return { outcome, staging, commit, discard, rollback, updateInstance };
715
+ }
566
716
 
567
- outcome = { modules: moduleRows, skills: skillRows, agentsMd: join(homeAbs, "AGENTS.md"), instanceJson: merged, blocks };
568
- } catch (error) {
569
- discard();
570
- throw error;
571
- }
572
- return outcome;
717
+ function safeName(name) {
718
+ if (typeof name !== "string" || !SAFE_COMPONENT_RE.test(name)) throw fail("E_MATERIALIZE_HOME", "invalid name in materialization transaction", { name });
719
+ return name;
573
720
  }
574
721
 
575
722
  /** Every entry under `dir` is a regular file or a directory (no symlinks, devices, sockets) — E_REMOTE_TREE_UNSAFE. */
package/lib/servers.mjs CHANGED
@@ -645,11 +645,11 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
645
645
  }
646
646
  const remote = checkRemote(target, io);
647
647
  // A saved route is keyed by name under its server id. An explicit name
648
- // that already has one here would overwrite that route on success: refuse
649
- // before the mutation (the roster shows the existing route; forget or
650
- // retire it first).
651
- const ii = oatsArgs.indexOf("--instance");
652
- const explicitName = ii >= 0 && oatsArgs[ii + 1] && !oatsArgs[ii + 1].startsWith("--") ? oatsArgs[ii + 1] : undefined;
648
+ // (--name, or --instance) that already has one here would overwrite that
649
+ // route on success: refuse before the mutation (the roster shows the
650
+ // existing route; forget or retire it first).
651
+ const valueOf = (flag) => { const i = oatsArgs.indexOf(flag); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
652
+ const explicitName = valueOf("--name") ?? valueOf("--instance");
653
653
  if (explicitName && readSnapshot(serverId, explicitName)) throw serverError("E_ROUTE_EXISTS", `a saved route for ${explicitName} through server ${serverId} already exists (${readSnapshot(serverId, explicitName).home}); retire it (oats retire ${explicitName} --server ${serverId}) or drop it (oats server forget ${serverId} --instance ${explicitName}) before spawning that name again`);
654
654
  // The remote roster: the soul's harness default for the support check,
655
655
  // and the remote agents root for the snapshot (the kernel's spawn result
@@ -662,8 +662,12 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
662
662
  // spawn-preview-2 is proven to answer --preview without spawning.
663
663
  const preview = oatsArgs.includes("--preview");
664
664
  if (preview) requireRemoteFeature(remote, target, "spawn-preview-2");
665
- // #1421 §3: the naming call runs on the host, through its routed preview.
666
- if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, "spawn-suggest-name");
665
+ // #1421 §3, #1490 §3: the naming call runs on the host, through its routed preview or apply. An
666
+ // older host is told nothing: a caller that would rather number the instance checks the host's
667
+ // features and does not send the flag; the route never drops it.
668
+ if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, preview ? "spawn-suggest-name" : "spawn-apply-suggest-name");
669
+ // An exact name is the host's to take: a host without spawn-name would refuse the flag, or worse.
670
+ if (oatsArgs.includes("--name")) requireRemoteFeature(remote, target, "spawn-name");
667
671
  const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
668
672
  if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
669
673
  // The host's preview with the two fields a routed spawn adds; never a
@@ -0,0 +1,101 @@
1
+ /** Read-only package-upgrade state shared by the upgrade act and session starts.
2
+ * Kept independent of core.mjs so checking a receipt never loads the lifecycle act. */
3
+ import { lstatSync, readdirSync } from "node:fs";
4
+ import { basename, join } from "node:path";
5
+ import { oatsError } from "./errors.mjs";
6
+ import { shellWord } from "./shell-word.mjs";
7
+ import { driftOf } from "./materialize.mjs";
8
+ import { parseStrictJson } from "./canonical-json.mjs";
9
+ import { readPortableBytes } from "./bounded-read.mjs";
10
+ import { canonicalHomePath } from "./real-path.mjs";
11
+
12
+ export const UPGRADE_RECEIPT_NAME_RE = /^upgrade-receipt\.[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\.json$/;
13
+ const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
14
+ const uncertainReceipt = (home, path) => Object.assign(oatsError("E_UPGRADE_PARTIAL", `cannot safely read package-upgrade receipt state at ${path}; cannot prove a session launch is safe. Inspect the receipt and retry its recorded upgrade command, or respawn the instance; nothing was stopped or started`), { details: { home, receipt: path } });
15
+
16
+ /** Read receipt state without following directory or receipt symlinks. A corrupt record cannot
17
+ * prove that provider adoption finished, so every reader refuses before lifecycle effects. */
18
+ export function readUpgradeReceipts(home) {
19
+ const directory = join(home, ".oats");
20
+ let before;
21
+ try { before = lstatSync(directory); }
22
+ catch (error) { if (error.code === "ENOENT") return []; throw uncertainReceipt(home, directory); }
23
+ if (!before.isDirectory()) throw uncertainReceipt(home, directory);
24
+ let names;
25
+ try { names = readdirSync(directory); }
26
+ catch { throw uncertainReceipt(home, directory); }
27
+ const rows = [];
28
+ for (const name of names.sort()) {
29
+ if (!UPGRADE_RECEIPT_NAME_RE.test(name)) continue;
30
+ const path = join(directory, name);
31
+ try {
32
+ const receipt = parseStrictJson(readPortableBytes(path));
33
+ const key = name.slice("upgrade-receipt.".length, -".json".length);
34
+ if (!object(receipt) || receipt.action !== "upgrade" || !["partial", "complete"].includes(receipt.status) || receipt.idempotencyKey !== key
35
+ || (receipt.steps !== undefined && !object(receipt.steps))
36
+ || ((receipt.status === "partial" || receipt.steps?.cleaned === false) && (typeof receipt.planRevision !== "string" || !receipt.planRevision.trim()))) throw new Error("invalid upgrade receipt");
37
+ rows.push({ path, receipt });
38
+ } catch { throw uncertainReceipt(home, path); }
39
+ }
40
+ try {
41
+ const after = lstatSync(directory);
42
+ if (!after.isDirectory() || after.dev !== before.dev || after.ino !== before.ino) throw new Error("receipt directory changed");
43
+ } catch { throw uncertainReceipt(home, directory); }
44
+ return rows;
45
+ }
46
+
47
+ function retryFor(home, receipt) {
48
+ const instance = typeof receipt.instance === "string" && receipt.instance ? receipt.instance : basename(home);
49
+ return { instance, command: `oats instance upgrade ${shellWord(instance)}${receipt.undo === true ? " --undo" : ""} --plan-revision ${shellWord(receipt.planRevision)} --idempotency-key ${shellWord(receipt.idempotencyKey)}` };
50
+ }
51
+
52
+ /** The shared start mutex is a directory for starts and a regular file for upgrades.
53
+ * A start never reclaims an upgrade file, even if its owner died during the initial write. */
54
+ export function upgradeMutexRetry(home) {
55
+ const path = join(home, ".oats-start.lock");
56
+ try { if (!lstatSync(path).isFile()) return null; }
57
+ catch { return null; }
58
+ try {
59
+ const owner = parseStrictJson(readPortableBytes(path));
60
+ if (object(owner) && owner.action === "upgrade" && owner.instance === basename(home)
61
+ && typeof owner.home === "string" && canonicalHomePath(owner.home) === canonicalHomePath(home)
62
+ && typeof owner.planRevision === "string" && owner.planRevision.trim()
63
+ && typeof owner.idempotencyKey === "string" && UPGRADE_RECEIPT_NAME_RE.test(`upgrade-receipt.${owner.idempotencyKey}.json`)
64
+ && (owner.undo === undefined || typeof owner.undo === "boolean")) return retryFor(home, owner).command;
65
+ } catch { /* An empty or incomplete write still belongs to the upgrade act. */ }
66
+ return `${retryFor(home, { planRevision: "<original-plan-revision>", idempotencyKey: "<original-idempotency-key>" }).command} (use the original revision and key, and include --undo if originally used)`;
67
+ }
68
+
69
+ /** A provider may already have adopted host state. A partial upgrade must finish forward
70
+ * before any launch hook or harness runs against the home's module copies. */
71
+ export function assertNoPartialUpgrade(home) {
72
+ for (const { path, receipt } of readUpgradeReceipts(home)) {
73
+ if (receipt.status !== "partial") continue;
74
+ const { instance, command } = retryFor(home, receipt);
75
+ throw Object.assign(oatsError("E_UPGRADE_PARTIAL", `the package upgrade of ${instance} is partial (${path}); nothing was stopped or started. Retry ${command} to finish it; if it cannot finish, respawn the instance`), {
76
+ details: { home, receipt: path, instance, idempotencyKey: receipt.idempotencyKey },
77
+ });
78
+ }
79
+ }
80
+
81
+ /** Swap and baseline already committed: launch is safe while event/cleanup finalization is retried. */
82
+ export function upgradeCleanupWarnings(home) {
83
+ return readUpgradeReceipts(home)
84
+ .filter(({ receipt }) => receipt.status === "complete" && receipt.steps?.cleaned === false)
85
+ .map(({ path, receipt }) => {
86
+ const { instance, command } = retryFor(home, receipt);
87
+ return `the package upgrade of ${instance} is complete, but staging cleanup remains (${path}); retry ${command} to finish cleanup`;
88
+ });
89
+ }
90
+
91
+ /** Only package modules that can move to a different locked commit. Removed packages
92
+ * and member drift remain information for status; neither is offered as an upgrade. */
93
+ export function packageUpgradeDrift(meta, { lock } = {}) {
94
+ return driftOf(meta, null, { lock })
95
+ .filter((row) => row.from.kind === "package" && row.status === "moved")
96
+ .map((row) => ({
97
+ capability: row.module,
98
+ recorded: { version: row.recorded.version ?? null, commit: row.recorded.commit ?? null },
99
+ locked: { version: row.current.version ?? null, commit: row.current.commit ?? null },
100
+ }));
101
+ }
package/lib/workspace.mjs CHANGED
@@ -552,6 +552,9 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
552
552
 
553
553
  /* ───────────────────────────── enumeration ────────────────────────────── */
554
554
 
555
+ /** The conventional directory shared by discovery and reads at a recorded soul commit. */
556
+ export const memberSoulPath = (name) => `souls/${name}`;
557
+
555
558
  const SOUL_FILE = /^([^/]+)\/soul\.yaml$/;
556
559
  const CAP_FILE = /^([^/]+)\/oats\.json$/;
557
560
 
@@ -580,7 +583,7 @@ async function enumerateRepo(remote, ref, key, commit) {
580
583
  for (const entry of await list("souls")) {
581
584
  const m = entry.type === "blob" && SOUL_FILE.exec(entry.path);
582
585
  if (!m) continue;
583
- const path = `souls/${m[1]}`;
586
+ const path = memberSoulPath(m[1]);
584
587
  const file = `${path}/soul.yaml`;
585
588
  let bytes;
586
589
  try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }