@awebai/oats 0.47.0 → 0.48.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.
package/bin/oats.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
31
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
32
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
33
+ findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
34
34
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
35
35
  } from "../lib/core.mjs";
36
36
  import {
@@ -53,7 +53,7 @@ import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/sched
53
53
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
54
54
 
55
55
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
56
- import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
56
+ import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
57
57
  import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
58
58
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
59
59
  import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
@@ -61,7 +61,7 @@ import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mj
61
61
 
62
62
  const rawArgs = process.argv.slice(2);
63
63
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
64
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
64
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
65
65
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
66
66
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
67
67
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -1775,26 +1775,55 @@ async function teamsContext(bail) {
1775
1775
  }
1776
1776
  const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
1777
1777
 
1778
- /** `oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label> | default <label>` —
1779
- * this deployment's teams (team model 3). Config only: never a provider call. */
1778
+ /** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
1779
+ * Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
1780
+ const TEAMS_FLAGS = {
1781
+ "": { "--max-age": true },
1782
+ add: { "--team": true, "--description": true, "--no-default": false },
1783
+ remove: {},
1784
+ default: { "--if-absent": false, "--expect": true },
1785
+ };
1786
+ /** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
1787
+ * reads it (the next word unless it starts with `--`). */
1788
+ function teamsUnknownFlag(sub) {
1789
+ const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
1790
+ for (let i = 1; i < args.length; i++) {
1791
+ const a = args[i];
1792
+ if (!a.startsWith("-")) continue;
1793
+ if (!Object.hasOwn(takes, a)) return a;
1794
+ if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
1795
+ }
1796
+ return undefined;
1797
+ }
1798
+
1799
+ /** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
1800
+ * default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
1801
+ * never a provider call. */
1780
1802
  async function teamsCmd() {
1781
1803
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1782
- const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] | oats teams remove <label> | oats teams default <label> [--dir <deployment>] [--json]";
1783
- const sub = positional(1);
1804
+ const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
1805
+ // A single-dash word (`-x`) is a flag, never the subcommand: teamsUnknownFlag names it.
1806
+ const sub = positional(1)?.startsWith("-") ? undefined : positional(1);
1784
1807
  if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
1808
+ const unknown = teamsUnknownFlag(sub);
1809
+ if (unknown !== undefined) {
1810
+ const form = sub ? `oats teams ${sub}` : "oats teams";
1811
+ bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
1812
+ }
1785
1813
  const label = sub ? positional(2) : undefined;
1786
1814
  if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
1787
1815
  const ctx = await teamsContext(bail);
1788
1816
  const V = await import("../lib/teams-verbs.mjs");
1789
1817
  let result = null;
1790
1818
  try {
1791
- if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description") });
1819
+ if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description"), noDefault: args.includes("--no-default") });
1792
1820
  else if (sub === "remove") result = V.teamsRemove(ctx, label);
1793
- else if (sub === "default") result = V.teamsDefault(ctx, label);
1821
+ else if (sub === "default") result = V.teamsDefault(ctx, label, { ifAbsent: args.includes("--if-absent"), expect: valueFlag("expect") });
1794
1822
  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
1795
1823
  const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
1796
- if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
1797
- if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
1824
+ if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed, ...(result.reused ? { reused: true } : {}) } : withObservation(doc)); return; }
1825
+ if (result?.reused) console.log(`Team ${label} is already declared with that id: nothing to change`);
1826
+ else if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
1798
1827
  console.log(`default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
1799
1828
  console.log(`local ${doc.localTeams === null ? "allowed (standalone)" : doc.localTeams ? "allowed (localTeams: true)" : "not allowed"}`);
1800
1829
  if (!doc.teams.length) console.log("teams (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
@@ -2612,35 +2641,41 @@ function retireCmd() {
2612
2641
  const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
2613
2642
  if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
2614
2643
  if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
2615
- let replayPath = null, childrenStopped = null, plannedExtraWorktrees;
2644
+ // What the plan says about recorded children holds on every apply path: the
2645
+ // retirement stops them first and keeps them (retireInstance, once it has
2646
+ // resolved the home). A guarded apply acts on the children of the plan it
2647
+ // revalidated; a plain or --self retire computes them as the plan does, and
2648
+ // passes none when there are none.
2649
+ let replayPath = null, plannedExtraWorktrees, fresh, children;
2616
2650
  if (planRev !== undefined) {
2617
2651
  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
2618
2652
  // Replay first: after a successful retire the home is gone, so the receipt
2619
2653
  // (beside the instances dir, keyed by the idempotency key) is the answer.
2620
2654
  const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
2621
2655
  for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
2622
- let fresh;
2623
2656
  try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2624
2657
  replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
2625
2658
  // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
2626
2659
  // move or remove one that no longer reads that way when it gets to them.
2627
2660
  plannedExtraWorktrees = fresh.facts.extraWorktrees;
2628
2661
  if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2629
- // The plan promised: recorded children are STOPPED first (bounded, never
2630
- // escalated) and retained. A child still running after the grace refuses
2631
- // the retirement — nothing is retired, the receipt names the pid.
2632
- childrenStopped = [];
2633
- for (const kid of fresh.facts.children) {
2634
- try { const s = stopInstanceSession(kid.home, {}); childrenStopped.push({ instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }); }
2635
- catch (e) { childrenStopped.push({ instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }); }
2636
- }
2637
- const running = childrenStopped.filter((k) => !k.ok);
2638
- if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
2662
+ children = fresh.facts.children;
2663
+ } else {
2664
+ const recorded = descendantsOf(root, name);
2665
+ if (recorded.length) children = recorded;
2639
2666
  }
2640
2667
  let r;
2641
- try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}) }); }
2642
- catch (e) { if (!e?.code) throw e; return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
2643
- if (childrenStopped) r.childrenStopped = childrenStopped;
2668
+ try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
2669
+ catch (e) {
2670
+ if (!e?.code) throw e;
2671
+ // A child still running (or whose stop could not be established) refused the retirement: the
2672
+ // guarded apply returns the plan it acted on, and the text names each child's reason.
2673
+ if (e.code === "E_CHILDREN_RUNNING") {
2674
+ const running = e.details.childrenStopped.filter((k) => !k.ok);
2675
+ return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
2676
+ }
2677
+ return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message);
2678
+ }
2644
2679
  if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
2645
2680
  // A retired home's wake jobs are forgotten (definitions only; nothing is
2646
2681
  // stopped by this); a deferred self-retire keeps them until the home is gone.
@@ -2677,6 +2712,7 @@ function retireCmd() {
2677
2712
  process.exit(1);
2678
2713
  }
2679
2714
  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
2715
+ for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}`);
2680
2716
  // Preserving work and not saying so leaves the operator believing it is gone,
2681
2717
  // which is most of the harm of deleting it. Name the classes and the path.
2682
2718
  for (const line of workRecoveryLines(r)) console.log(line);
@@ -3414,7 +3450,7 @@ function versionCmd() {
3414
3450
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
3415
3451
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
3416
3452
  // never listed.
3417
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3453
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3418
3454
  return;
3419
3455
  }
3420
3456
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4217,10 +4253,14 @@ Usage:
4217
4253
  [--max-age <s>] (souls have no private mode), with origin
4218
4254
  (member <key> @ <commit> | package <id> v<ver>) and its
4219
4255
  teams on this deployment
4220
- oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
4221
- | default <label> [--dir <d>] this deployment's teams (shared + local), the
4256
+ oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label>
4257
+ | default <label> [--if-absent | --expect <label>]
4258
+ [--dir <d>] this deployment's teams (shared + local), the
4222
4259
  [--max-age <s>] (the read form only) default, the workspace's souls:; add/remove/default
4223
- edit oats-local.yaml (only with localTeams: true)
4260
+ edit oats-local.yaml (only with localTeams: true);
4261
+ --no-default: the mapping only (an exact repeat is
4262
+ reuse); --if-absent / --expect: set the default only
4263
+ where there is none / it is <label>
4224
4264
  oats soul teams <soul>|'*' [--dir <d>] which teams a soul may join here, its default, and
4225
4265
  [--max-age <s>] [--json] why (the workspace's souls: and local teams)
4226
4266
  oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
@@ -495,6 +495,14 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
495
495
  launch hook that answers without `meta` keeps its previous entry; a start whose
496
496
  preparation fails changes nothing.
497
497
 
498
+ A launch hook's `brief` is not used. A home's `TASK.md` (which carries the
499
+ spawn hooks' briefs) and `AGENTS.md` are composed once, at spawn, and no start
500
+ rewrites them. A provider whose state changes at a start records it in `meta`.
501
+ `oats inspect --home <abs> --json` reads the served identity a provider
502
+ recorded there (the messaging provider's, when it has one) as `identity`. A
503
+ spawn brief that describes such state should say it is the state at spawn and
504
+ point to that command.
505
+
498
506
  A launch hook may do idempotent provider registration on a real start (an
499
507
  aweb home registering with the host wake broker, for example). How the
500
508
  kernel runs it depends on whether its capability declares **preview
@@ -63,7 +63,7 @@ refused (`E_WORKSPACE_SCHEMA`).
63
63
  | `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
64
64
  | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
65
65
  | `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
66
- | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
66
+ | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
67
67
  | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
68
68
  | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
69
69
  | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
@@ -40,7 +40,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
40
40
  "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
41
41
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
42
42
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
43
- "automation-descriptions","souls-capabilities","soul-composed-instructions"],
43
+ "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default"],
44
44
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
45
45
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
46
46
  "capabilityShowApi":1}
@@ -112,6 +112,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
112
112
  | `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
113
113
  | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
114
114
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
115
+ | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
115
116
 
116
117
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
117
118
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -367,7 +368,7 @@ An instance subject, abridged:
367
368
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
368
369
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
369
370
  | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
370
- | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null` |
371
+ | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
371
372
  | `problems` | below |
372
373
 
373
374
  **Soul row** (`soulsApi: 2`). For a home it is read from the recorded
@@ -1250,9 +1251,9 @@ unknown.
1250
1251
 
1251
1252
  ```text
1252
1253
  oats teams [--dir <d>] [--max-age <s>] --json
1253
- oats teams add <label> --team <id> [--description <d>] --json
1254
+ oats teams add <label> --team <id> [--description <d>] [--no-default] --json
1254
1255
  oats teams remove <label> --json
1255
- oats teams default <label> --json
1256
+ oats teams default <label> [--if-absent | --expect <label>] --json
1256
1257
  ```
1257
1258
 
1258
1259
  ```json
@@ -1284,13 +1285,41 @@ oats teams default <label> --json
1284
1285
  still runs there: taking local teams away is the last step of committing
1285
1286
  them in the workspace.
1286
1287
  - **`add`**: the first team added also becomes the local `defaultTeam`. A
1287
- label already declared is `E_TEAM_EXISTS {label, from}`; a bad label or no
1288
- `--team` is `E_BAD_ARGS`.
1288
+ label already declared is `E_TEAM_EXISTS {label, from, observed: {label,
1289
+ team, from}}` (`observed` is the declared mapping; `from` is `"local"` or
1290
+ `"shared"`); a bad label or no `--team` is `E_BAD_ARGS`.
1291
+ - **`add --no-default`** (feature `teams-conditional-default`) writes the
1292
+ mapping and never touches `defaultTeam`. A mapping already declared with
1293
+ the same label and the same team id (local or shared) is reuse: the answer
1294
+ is `changed: false, reused: true`, so a setup can retry it. The description
1295
+ is neither compared nor changed. The same label with another id is
1296
+ `E_TEAM_EXISTS` as above. `reused` appears only on that answer. Where local
1297
+ teams are not allowed, `add --no-default` is refused with local-teams-closed
1298
+ like every `add`, before reuse is considered.
1289
1299
  - **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
1290
1300
  {label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
1291
1301
  at}` (a label in both files can be removed locally); unknown is
1292
1302
  `E_TEAM_UNKNOWN {label}`.
1293
1303
  - **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
1304
+ - **`default --if-absent`** sets it only where the deployment has no effective
1305
+ default (this document's `defaultTeam` is `null`); **`default --expect
1306
+ <label0>`** only where the effective default's label is `<label0>`, local
1307
+ or inherited from the workspace (feature `teams-conditional-default`). The
1308
+ two together are `E_BAD_ARGS`. A failed condition is `E_TEAM_DEFAULT_MISMATCH
1309
+ {expected: {absent: true} | {label}, observed}`, `observed` being the
1310
+ `defaultTeam` exactly as this document reports it (or `null`); nothing was
1311
+ written. A soul's `souls:` default is not the deployment's and is not
1312
+ looked at. The refusals above run first, in order: `E_BAD_ARGS`,
1313
+ local-teams-closed, `E_TEAM_UNKNOWN`, then the condition. When the
1314
+ condition holds and `<label>` already is the local default, `changed` is
1315
+ `false`.
1316
+ - **Flags**: each form refuses a flag it does not take with `E_USAGE {flag}`,
1317
+ naming the flag and the usage, before anything is read. `add` takes
1318
+ `--team`, `--description`, `--no-default`; `remove` none; `default`
1319
+ `--if-absent`, `--expect`; every form `--dir` and `--json`, and the read
1320
+ form `--max-age` (on a write form, `--max-age` is the kernel's own
1321
+ `E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
1322
+ answer, as for every command.
1294
1323
  - A write that would introduce an unknown reference is refused with that
1295
1324
  code; an invalid result is `E_WORKSPACE_SCHEMA`.
1296
1325
  - **Writes** edit `oats-local.yaml` in place and touch only the entries that
@@ -1298,7 +1327,22 @@ oats teams default <label> --json
1298
1327
  entries, are kept. Each verb re-reads the file and judges its refusals on it
1299
1328
  as it is now, and writes only if the file did not change meanwhile (else it
1300
1329
  redoes the edit on the new content). A file that keeps changing is
1301
- `E_LOCAL_CHANGED {path}`; nothing was written.
1330
+ `E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
1331
+ and `--expect` is judged the same way, on the file as it is now and again on
1332
+ every redo.
1333
+ - **Concurrency.** Every `add`, `remove` and `default` holds
1334
+ `<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
1335
+ Among concurrent `oats teams` writers on one deployment, a conditional write
1336
+ therefore never overwrites a default another of them set: when two race, the
1337
+ later one sees the earlier result and refuses with
1338
+ `E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
1339
+ {path, lock}`, naming the directory to remove when no oats process is
1340
+ editing; nothing was written. The limits: a person or tool editing
1341
+ `oats-local.yaml` directly does not take the lock (the content compare still
1342
+ catches most such edits, but not one landing between the compare and the
1343
+ rename), and changes to the committed `oats-workspace.yaml` (a pull, a
1344
+ merge) are not serialized with it: the condition reads the workspace file
1345
+ when it is judged, and that is the only promise.
1302
1346
 
1303
1347
  <a id="oats-soul-teams"></a>
1304
1348
  ### `oats soul teams`
@@ -2848,14 +2892,32 @@ A first retire prints the **raw receipt**, not an envelope:
2848
2892
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
2849
2893
  `{…, alreadyScheduled: true, requestedAt}`.
2850
2894
 
2895
+ **Recorded children**, on every apply (plain, guarded and `--self`), as the
2896
+ plan says: each child the plan lists is stopped first (bounded SIGTERM,
2897
+ never escalated) and kept, once the retire has resolved the home and before
2898
+ the instance's own session is stopped. `childrenStopped[]` lists them,
2899
+ deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
2900
+ `{instance, home, ok: false, code, message, stillRunning}`. A plain or
2901
+ `--self` receipt carries it only when there are children; a guarded receipt
2902
+ always does (`[]` when there are none). One child still running after the
2903
+ grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
2904
+ `E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
2905
+ `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
2906
+ `code`). **`--force` does not bypass it**: `--force` covers incomplete
2907
+ cleanup, not a running child. A `--self` retirement stops the children
2908
+ recorded when it was scheduled that are still instances (a child retired in
2909
+ between is skipped), in its detached completion before it stops the caller;
2910
+ a refusal there leaves the caller's window and home in place and
2911
+ writes `{ok: false, error: {code: "E_CHILDREN_RUNNING"}, childrenStopped,
2912
+ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
2913
+
2851
2914
  **Guarded apply** (what the Desktop sends): `--plan-revision` and
2852
2915
  `--idempotency-key` together.
2853
2916
  - A used key replays its receipt as an **envelope** with `replayed: true`
2854
2917
  (receipts live beside the instances directory and outlive the home).
2855
2918
  - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
2856
- - Children are stopped first (never escalated) and kept; `childrenStopped[]`
2857
- lists them. One still running refuses everything: `E_CHILDREN_RUNNING
2858
- {childrenStopped, plan}`.
2919
+ - The children stopped are those of the revalidated plan, and a refusal
2920
+ carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
2859
2921
  - A first guarded retire prints the raw receipt with `planRevision`,
2860
2922
  `idempotencyKey` and `replayed: false`.
2861
2923
 
@@ -744,6 +744,9 @@ oats session attach --home /abs/home
744
744
  harness, `shell` for a fallback shell,
745
745
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
746
746
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
747
+ A home without its session receipt is refused with
748
+ `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for; what
749
+ to do is in [souls and instances](souls-and-instances.md#retire).
747
750
  Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
748
751
  live claim that the instance needs input from a human, `{since, producer,
749
752
  reason, message}`, or `null`; it is non-null only for a running harness
@@ -368,3 +368,22 @@ and acts on every existing session through its recorded socket
368
368
  `list-windows`, `new-window` (a window id) and `set-option`.
369
369
  - A server a test starts is killed by its socket, never by name and never
370
370
  with a bare `tmux kill-server`.
371
+
372
+ Nor does a test depend on where or how the suite runs:
373
+
374
+ - A worker whose working directory is inside an instance home (a developer
375
+ agent running the suite from its work tree) is that instance to the
376
+ kernel. `isolateSessionEnvironment` leaves it; a fixture that builds its
377
+ environment itself calls `leaveEnclosingInstance(base)` and moves back
378
+ when it is done.
379
+ - `isolateSessionEnvironment` drops `CLAUDECODE`, which a worker inherits
380
+ from a Claude Code session: a server the worker starts would hold it.
381
+ - An expected path is built on a canonical fixture base,
382
+ `realpathSync(mkdtempSync(…))`: the platform's temporary directory can be
383
+ a symlink (`/var` on macOS), and the kernel builds the paths it reports on
384
+ its working directory, which the OS gives as the physical path.
385
+ - A probe of the host that reads under `HOME` (the scheduler's installed
386
+ unit) runs with the fixture's own `HOME`.
387
+ - A fixture the filesystem may not represent (a file name that is not valid
388
+ UTF-8, which APFS refuses) is probed in the fixture directory and skipped
389
+ with its reason only when refused; Linux CI runs it.
@@ -9,14 +9,15 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.7.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.8.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
14
+ | `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
15
+ | `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
19
19
  | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
20
+ | `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
20
21
 
21
22
  Each package lives in its own `awebai/oats-*` repository except
22
23
  `oats.framework`, whose payload root is `oats-package/` here. A capability id
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v4.1.1` or `oats-framework/v1.7.0`) and the payload path. An id
54
+ convention (`v4.1.1` or `oats-framework/v1.8.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.7.0
77
+ oats.framework: v1.8.0
78
78
  oats.okf: v4.1.1
79
- oats.aweb: v1.21.1
79
+ oats.aweb: v1.23.2
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.21.1 # a catalog version
137
+ oats package add oats.aweb v1.23.2 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -339,11 +339,11 @@ A soul that names one of the package's capabilities with
339
339
  "policy": "docs/official-catalog.md",
340
340
  "packages": {
341
341
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
342
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.7.0", "path": "oats-package" }
342
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
343
343
  }
344
344
  }
345
345
  ```
346
346
 
347
- `ref` carries the tag convention: a workspace's `oats.framework: v1.7.0`
348
- resolves to tag `oats-framework/v1.7.0`. Resolving through the catalog never
347
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.8.0`
348
+ resolves to tag `oats-framework/v1.8.0`. Resolving through the catalog never
349
349
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,106 @@
1
+ # OATS 0.48.0
2
+
3
+ 2026-10-08
4
+
5
+ ## Added
6
+
7
+ - **Conditional team default and mapping-only add (#771), feature
8
+ `teams-conditional-default`.** `oats teams default <label> --if-absent`
9
+ sets the local default only where the deployment has no effective default;
10
+ `--expect <label0>` only where the effective default (local, or inherited
11
+ from the workspace) is `<label0>`. A failed condition is
12
+ `E_TEAM_DEFAULT_MISMATCH {expected, observed}` and writes nothing.
13
+ `oats teams add <label> --team <id> --no-default` writes the mapping without
14
+ touching `defaultTeam`; the same label and id already declared is reuse
15
+ (`changed: false, reused: true`). `E_TEAM_EXISTS` also carries `observed:
16
+ {label, team, from}`. Every `oats teams` write holds
17
+ `<deployment>/.agents/locks/local.lock`, so the later of two racing
18
+ conditional writes sees the earlier one and refuses with
19
+ `E_TEAM_DEFAULT_MISMATCH`; a lock still held after 5 s is `E_LOCAL_BUSY`,
20
+ with nothing written. `teamsApi`
21
+ stays 2: the `oats teams --json` shape is unchanged. Callers check the
22
+ feature before passing the flags, because older kernels ignore them, and
23
+ there `--if-absent` is an unconditional set.
24
+
25
+ ## Changed
26
+
27
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.49.0`.** The compatibility band
28
+ admits 0.48; existing feature gates remain unchanged.
29
+
30
+ - **`oats teams` refuses flags it does not take.** Each form (`oats teams`,
31
+ `add`, `remove`, `default`) answers an unknown flag with `E_USAGE {flag}`,
32
+ naming it and the usage, before anything is read or written. Before, they
33
+ were ignored. `--server` on `oats teams` is now refused too: teams has never
34
+ been routed to a server. A script that passes stray flags must drop them.
35
+
36
+ - **The workspace pins oats.framework 1.8.0 and oats.engineering 1.9.0.**
37
+ The official catalog resolves bare `oats.framework` versions to
38
+ `oats-framework/v1.8.0` (oats.support 1.0.0, the support desk role), and
39
+ `oats.engineering` to `v1.9.0`. That adds oats.maintainer's
40
+ `/support-maintainer` skill: a maintainer that serves the support desk's
41
+ tickets. The capability mirrors under `mirrors/` are regenerated from the
42
+ v1.9.0 tag and their trees equal the tag's. Running instances keep what
43
+ they were spawned with; new spawns pick these up after `oats sync`.
44
+
45
+ - **The workspace and official catalog pin oats.aweb 1.23.2.** The generated
46
+ `mirrors/oats-aweb` payload equals the provider v1.23.2 tag tree. This adds
47
+ verified LOCAL join mapping/default readback and explicit LOCAL identity
48
+ selectors at launch and preview (1.23.1), and GLOBAL grant metadata that
49
+ records the app snapshot from each successful native mint receipt: Comms
50
+ labels it as the at-spawn snapshot, inspect shows the current recorded
51
+ metadata, and preview warnings say whether it is retained or unknown
52
+ pending renewal (1.23.2). That snapshot is not a live app acceptance. Existing captured homes
53
+ do not adopt the changes automatically; this pin does not perform sync,
54
+ restart or live acceptance.
55
+
56
+ - **oats.apps 1.0.0 is a new official package.** It exports `oats.folio` and
57
+ `oats.library`, additive guidance capabilities for the aweb Folio and Library
58
+ apps (`aw >=1.36.26`; OATS 0.47.0 or later), and the catalog aliases both
59
+ ids to the package. The generated `mirrors/oats-folio` and
60
+ `mirrors/oats-library` equal the v1.0.0 tag's payload trees. The workspace
61
+ adds `awebai/oats-apps` as a member (its expert soul `oats-apps-expert`) and
62
+ pins `oats.apps: git:github.com/awebai/oats-apps@v1.0.0`: an installed CLI
63
+ resolves bare versions through the catalog it shipped with, and 0.47.0's has
64
+ no `oats.apps`, so the pin goes bare once every deployment's CLI carries
65
+ this entry. No soul selects either capability yet, and no workspace default
66
+ is added.
67
+
68
+ ## Fixed
69
+
70
+ - **Every `oats retire` stops recorded children first, as its plan says
71
+ (#778).** `oats retire <name> --plan` has always said that recorded child
72
+ instances "are stopped first (bounded SIGTERM, never escalated) and
73
+ retained" and that "a child still running after the grace refuses the
74
+ retirement", but before 0.48.0 only the guarded apply (`--plan-revision`
75
+ with `--idempotency-key`, what the Desktop sends) did it. A plain
76
+ `oats retire <name>` and a `--self` retirement left the children running,
77
+ attached ones on a work tree that had just been removed, with no stop
78
+ event.
79
+ - **Behavior change.** A plain `oats retire` and `--self` now stop recorded
80
+ children first and keep them. They refuse, retiring nothing, when one
81
+ won't stop or its session can't be established: `E_CHILDREN_RUNNING
82
+ {childrenStopped}`, exit 1, and the text names each child and its code
83
+ (`children still running: <name> (<code>); nothing retired`). `--force`
84
+ does not bypass it: end the child's session yourself (the receipt's
85
+ `stillRunning` names its processes), then retry.
86
+ - The receipt lists the children as `childrenStopped[]` (absent when there
87
+ are none), and the text prints `child <name>: stopped` or
88
+ `already idle` for each.
89
+ - `--self` stops the children recorded when the retirement was scheduled
90
+ (skipping any retired since), in its detached completion before it stops
91
+ the caller. A refusal leaves the caller's window and home in place and
92
+ writes `E_CHILDREN_RUNNING` with `childrenStopped` and the `retry` command
93
+ to the result file that `oats status` reports.
94
+ - The guarded apply is unchanged for the Desktop. It now stops children
95
+ only after the retire's own read-only refusals, so a retire refused
96
+ there leaves its children running.
97
+
98
+ - **A home without its session receipt says what was looked for and what to
99
+ do (#762).** `session inspect`, `start` and `restart` refused such a home
100
+ with a bare `ENOENT`. The `E_RUNTIME_ENDPOINT_UNKNOWN` refusal now names
101
+ the receipt path it looked for, says to address the home exactly as
102
+ `oats status` prints it (a different spelling of the path looks for the
103
+ receipt elsewhere), and otherwise names the causes and the remedy: stop its
104
+ session yourself if one runs, then `oats retire <name> --plan` and
105
+ `oats retire <name>`, and respawn. The code is unchanged. The receipt's key
106
+ for a differently spelled path is #780.
@@ -431,6 +431,13 @@ takes a final capture of notes and the session record into durable custody; an
431
431
  incomplete capture keeps the home for a retry. Retirement never waits for a
432
432
  model or GitHub: processing continues after the home is gone.
433
433
 
434
+ Recorded children (the instances whose recorded parent chain reaches this
435
+ one) are stopped first, never escalated, and kept: their homes stay. If one is
436
+ still running after the grace, or its stop cannot be established, retire
437
+ refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
438
+ bypass it. This holds for plain, guarded and `--self` retires alike
439
+ ([desktop-cli-api.md](desktop-cli-api.md)).
440
+
434
441
  Before any retire hook runs, retire preserves the instance's uncommitted and
435
442
  unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
436
443
  the summary. One retire writes at most one recovery directory. A worktree
@@ -753,8 +760,16 @@ exist under "not copied", by name, with the declaring capability. The
753
760
  declaration is recorded at spawn: a home spawned before its capability
754
761
  declared them gains no exclusion from a package update, and is copied whole.
755
762
 
756
- Retire stops the harness through the home's session receipt. A home spawned
757
- before 0.25.9 has none. It retires only when its session is observably gone:
763
+ Retire stops the harness through the home's session receipt, kept beside the
764
+ home in the instances directory's `.oats-retirement/baselines/` and keyed by
765
+ the home's path. First address the home exactly as `oats status` prints it: a
766
+ different spelling of its path (letter case, a deployment directory moved
767
+ since the spawn) looks for the receipt elsewhere. A home can also be without
768
+ its receipt because it was spawned before 0.25.9, it was copied, the
769
+ `.oats-retirement` beside it was removed, or its creation did not finish;
770
+ `session inspect`, `start` and `restart` then refuse with
771
+ `E_RUNTIME_ENDPOINT_UNKNOWN` naming the receipt path they looked for. Such a
772
+ home retires only when its session is observably gone:
758
773
  instance.json records no launch, or the recorded tmux server is not running,
759
774
  or the recorded window is gone and no pane on that server works in the home;
760
775
  and, always, no live process on this host works in the home (a harness
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.7.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.8.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v4.1.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -421,11 +421,26 @@ the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
421
421
  ```
422
422
  oats teams [--json] # the teams, ids, the default, localTeams, the workspace's souls:, problems
423
423
  oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
424
+ oats teams add <label> --team <id> --no-default # the mapping only; the same label and id again is reuse
424
425
  oats teams remove <label> # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
425
426
  oats teams default <label> # the local default
427
+ oats teams default <label> --if-absent # ... only where there is no effective default
428
+ oats teams default <label> --expect <label0> # ... only where the effective default is <label0>
426
429
  oats soul teams <soul>|'*' [--json] # a soul's default and teams here, and which souls: key gave them
427
430
  ```
428
431
 
432
+ `--if-absent` and `--expect` make a setup safe to run against a deployment
433
+ whose default it has not chosen: the condition is the effective default that
434
+ `oats teams` reports (the local one, else the workspace's), judged when the
435
+ file is written, and a failed one (`E_TEAM_DEFAULT_MISMATCH`) reports what it
436
+ found and writes nothing. A soul's `souls:` default is not the deployment's
437
+ default and is not looked at. Concurrent `oats teams` writes on one deployment
438
+ are serialized, so of two racing conditional writes the later one refuses;
439
+ hand edits to `oats-local.yaml` and changes to `oats-workspace.yaml` are not
440
+ serialized with them. Each form refuses a flag it does not take (`E_USAGE`).
441
+ Callers check for the feature `teams-conditional-default` in `oats version
442
+ --json` first: an older kernel ignores these flags.
443
+
429
444
  The messaging provider's own setup creates provider teams (see the provider's
430
445
  documentation). The spawn preview, `inspect` and `oats souls` report a soul's
431
446
  `teams` and `defaultTeam`; readiness reports the team problems in
package/lib/core.mjs CHANGED
@@ -5456,16 +5456,26 @@ function launchStateAgrees(meta, authority) {
5456
5456
  ["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
5457
5457
  }
5458
5458
 
5459
+ /** The refusal for a home whose session receipt file does not exist where its path says it is. The
5460
+ * receipt is keyed by the home's path, so a different spelling of that path looks elsewhere. */
5461
+ function missingSessionReceipt(home, receiptPath) {
5462
+ return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${receiptPath}. First address the home exactly as \`oats status\` prints it (a different spelling — letter case, a moved deployment directory — looks for the receipt elsewhere). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
5463
+ }
5464
+
5459
5465
  /** Session control uses the independent endpoint receipt. */
5460
5466
  function instanceSessionTarget(home) {
5461
5467
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
5462
5468
  home = realPathOrNearest(home);
5463
5469
  refuseHerdrHome(home);
5470
+ const receiptPath = retirementBaselinePath(home);
5464
5471
  let baseline, meta;
5465
5472
  try {
5466
- baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8"));
5473
+ baseline = JSON.parse(readFileSync(receiptPath, "utf8"));
5467
5474
  meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
5468
- } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`); }
5475
+ } catch (e) {
5476
+ if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home, receiptPath);
5477
+ throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`);
5478
+ }
5469
5479
  const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
5470
5480
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
5471
5481
  if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
@@ -5593,6 +5603,17 @@ export function stopInstanceSession(home, o = {}) {
5593
5603
  return { home: s.home, backend: s.target.backend, stopped: true, alreadyIdle: false, state: receipt.state, receipt };
5594
5604
  }
5595
5605
 
5606
+ /** What a retire plan promises about recorded children, applied: each is stopped
5607
+ * (default grace, never escalated) in the order given (the plan's: deepest first)
5608
+ * and kept. Every outcome is collected, so a refusal names each child that is
5609
+ * still running or whose stop could not be established. */
5610
+ function stopRecordedChildren(children) {
5611
+ return children.map((kid) => {
5612
+ try { const s = stopInstanceSession(kid.home, {}); return { instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }; }
5613
+ catch (e) { return { instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }; }
5614
+ });
5615
+ }
5616
+
5596
5617
  export async function attachInstanceSession(home) {
5597
5618
  const s = instanceSessionTarget(home);
5598
5619
  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
@@ -5995,7 +6016,10 @@ export function startInstanceSession(home, o = {}) {
5995
6016
  checkRoots();
5996
6017
  const baselinePath = retirementBaselinePath(realHome);
5997
6018
  let baseline;
5998
- try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`); }
6019
+ try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
6020
+ if (e.code === "ENOENT") throw missingSessionReceipt(realHome, baselinePath);
6021
+ throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`);
6022
+ }
5999
6023
  if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
6000
6024
  baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
6001
6025
  writeJsonAtomic(baselinePath, baseline, 0o600);
@@ -7295,7 +7319,9 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
7295
7319
  instance: name, agent: found.agent.name, root: resolve(root),
7296
7320
  requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
7297
7321
  // A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
7298
- options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}) }, resultPath,
7322
+ options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
7323
+ // The recorded children as they were when the retirement was scheduled: the completion stops them first.
7324
+ ...(Array.isArray(o.children) ? { children: o.children.map((c) => ({ instance: c.instance, home: c.home })) } : {}) }, resultPath,
7299
7325
  };
7300
7326
  const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
7301
7327
  for (const k of CORE_LAUNCH_ENV) delete env[k];
@@ -7374,10 +7400,11 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
7374
7400
  result = retireInstance(intent.root, intent.instance, {
7375
7401
  home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
7376
7402
  ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
7403
+ ...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
7377
7404
  ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
7378
7405
  });
7379
7406
  } catch (e) {
7380
- record({ ok: false, error: { code: e.code, message: e.message }, ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
7407
+ record({ ok: false, error: { code: e.code, message: e.message }, ...(e.details?.childrenStopped ? { childrenStopped: e.details.childrenStopped } : {}), ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
7381
7408
  console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
7382
7409
  return false;
7383
7410
  }
@@ -7555,6 +7582,19 @@ export function retireInstance(root, name, o = {}) {
7555
7582
  throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
7556
7583
  }
7557
7584
  }
7585
+ // The plan's promise about recorded children (`o.children`, computed the way
7586
+ // the plan computes them): stopped first and kept, after every refusal above
7587
+ // that changes nothing and before this instance is quiesced. One still running,
7588
+ // or whose stop could not be established, refuses the retirement: nothing is
7589
+ // retired, nothing is escalated, and --force does not bypass it. A child whose
7590
+ // instance.json is gone by now (a --self snapshot's child retired in between)
7591
+ // is no longer an instance, and the plan would not list it: it is not stopped.
7592
+ let childrenStopped;
7593
+ if (Array.isArray(o.children)) {
7594
+ childrenStopped = stopRecordedChildren(o.children.filter((kid) => existsSync(join(kid.home, "instance.json"))));
7595
+ const running = childrenStopped.filter((k) => !k.ok);
7596
+ if (running.length) throw Object.assign(oatsError("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`), { details: { childrenStopped } });
7597
+ }
7558
7598
  // `=` forces exact matching: tmux targets otherwise PREFIX-match window names.
7559
7599
  // A no-launch instance is already quiesced. A launched one must have exact
7560
7600
  // window absence established before recovery copying begins.
@@ -7953,7 +7993,7 @@ export function retireInstance(root, name, o = {}) {
7953
7993
  rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
7954
7994
  }
7955
7995
 
7956
- const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
7996
+ const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
7957
7997
  const w = [...(hookResults?.warnings || [])];
7958
7998
  if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
7959
7999
  if (isCapturedHome(meta) && !quarantine) {
@@ -8,12 +8,14 @@
8
8
  * `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
9
9
  */
10
10
  import { readFileSync } from "node:fs";
11
+ import { join } from "node:path";
11
12
  import YAML from "yaml";
12
13
  import { parseConfigData } from "./config-data.mjs";
13
14
  import { oatsError } from "./errors.mjs";
14
15
  import { teamLabelProblem, validateLocal } from "./workspace.mjs";
15
16
  import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
16
17
  import { writeFileAtomic } from "./packages.mjs";
18
+ import { withDirLock } from "./dir-lock.mjs";
17
19
 
18
20
  export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
19
21
  const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -99,8 +101,19 @@ function applyState(doc, before, next) {
99
101
  * `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
100
102
  * allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
101
103
  * there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
104
+ * The whole read-compare-write runs under the deployment's local lock (localLock), so among `oats teams`
105
+ * writers the compare and the rename are one step: a conditional write sees every earlier one.
102
106
  */
103
107
  function editLocal(ctx, { verb, writes }, mutate) {
108
+ const lock = localLock(ctx);
109
+ return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { verb, writes }, mutate), {
110
+ retryMs: 5000,
111
+ busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats teams command is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
112
+ });
113
+ }
114
+ /** The lock every `oats teams` mutation holds: in the deployment's kernel state tree, never beside the files. */
115
+ const localLock = (ctx) => join(ctx.deployment, ".agents", "locks", "local.lock");
116
+ function editLocalLocked(ctx, { verb, writes }, mutate) {
104
117
  for (let attempt = 0; attempt < 5; attempt++) {
105
118
  const { text, doc, local: current } = readLocal(ctx);
106
119
  const model = modelOf(ctx, current);
@@ -128,20 +141,25 @@ const assertLabel = (label) => {
128
141
  if (problem) throw fail("E_BAD_ARGS", `not a team label (lowercase letters, digits, and . _ - after the first; at most 64 characters): ${problem}`, { label });
129
142
  };
130
143
 
131
- /** `oats teams add <label> --team <id> [--description <d>]` → { changed, local }. */
132
- export function teamsAdd(ctx, label, { team, description } = {}) {
144
+ /** `oats teams add <label> --team <id> [--description <d>] [--no-default]` → { changed, local, reused? }.
145
+ * `noDefault`: the mapping only, `defaultTeam` never touched; a mapping already there with the same label
146
+ * and team id (local or shared; the description is not compared) is reuse → { changed: false, reused: true }. */
147
+ export function teamsAdd(ctx, label, { team, description, noDefault = false } = {}) {
133
148
  assertLabel(label);
134
149
  if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
135
150
  if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
136
- return editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
151
+ let reused = false;
152
+ const result = editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
137
153
  if (model.labels.has(label)) {
138
- const from = model.labels.get(label).from;
139
- throw fail("E_TEAM_EXISTS", `team ${label} is already declared (${from === "shared" ? "shared, in oats-workspace.yaml" : "local, in oats-local.yaml"})${from === "local" ? ": remove it first (`oats teams remove`) to redefine it" : ""}`, { label, from });
154
+ const { from, team: existing } = model.labels.get(label);
155
+ if (noDefault && existing === team.trim()) { reused = true; return; }
156
+ throw fail("E_TEAM_EXISTS", `team ${label} is already declared (${from === "shared" ? "shared, in oats-workspace.yaml" : "local, in oats-local.yaml"})${from === "local" ? ": remove it first (`oats teams remove`) to redefine it" : ""}`, { label, from, observed: { label, team: existing, from } });
140
157
  }
141
158
  s.teams[label] = { team: team.trim(), ...(typeof description === "string" && description ? { description } : {}) };
142
- // The first team added becomes the deployment's default.
143
- if (s.defaultTeam === null) s.defaultTeam = label;
159
+ // The first team added becomes the deployment's default (unless --no-default).
160
+ if (s.defaultTeam === null && !noDefault) s.defaultTeam = label;
144
161
  });
162
+ return reused ? { ...result, reused } : result;
145
163
  }
146
164
 
147
165
  /** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
@@ -160,10 +178,23 @@ export function teamsRemove(ctx, label) {
160
178
  });
161
179
  }
162
180
 
163
- /** `oats teams default <label>`: a label of either file. */
164
- export function teamsDefault(ctx, label) {
181
+ /** Refuse unless the effective default (the `defaultTeam` of `oats teams --json`) is what the caller
182
+ * expects: none (`ifAbsent`), or the label `expect`. Soul defaults are not the deployment's and not looked at. */
183
+ function assertDefaultPrecondition(model, { ifAbsent, expect }) {
184
+ const observed = deploymentDefault(model);
185
+ if (ifAbsent ? observed === null : observed?.label === expect) return;
186
+ const now = observed === null ? "there is no default team" : `the default team is ${observed.label} (${observed.from === "deployment" ? "the deployment's, in oats-local.yaml" : "the workspace's, from oats-workspace.yaml"})`;
187
+ const wanted = ifAbsent ? "--if-absent sets it only where there is none" : `--expect ${expect} sets it only where the default is ${expect}`;
188
+ throw fail("E_TEAM_DEFAULT_MISMATCH", `${now}: ${wanted}; nothing was written`, { expected: ifAbsent ? { absent: true } : { label: expect }, observed });
189
+ }
190
+
191
+ /** `oats teams default <label> [--if-absent | --expect <label0>]`: a label of either file. The condition is
192
+ * judged inside the edit, on the file as it is now (and again on every retry), after today's refusals. */
193
+ export function teamsDefault(ctx, label, { ifAbsent = false, expect } = {}) {
194
+ if (ifAbsent && expect !== undefined) throw fail("E_BAD_ARGS", "oats teams default takes --if-absent or --expect <label>, not both", { label });
165
195
  return editLocal(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
166
196
  if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
197
+ if (ifAbsent || expect !== undefined) assertDefaultPrecondition(model, { ifAbsent, expect });
167
198
  s.defaultTeam = label;
168
199
  });
169
200
  }
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.21.1",
11
+ "ref": "v1.23.2",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.8.1",
31
+ "ref": "v1.9.0",
32
32
  "path": "oats-package"
33
33
  },
34
34
  "oats.cloning": {
@@ -36,9 +36,14 @@
36
36
  "ref": "v1.0.1",
37
37
  "path": "oats-package"
38
38
  },
39
+ "oats.apps": {
40
+ "url": "https://github.com/awebai/oats-apps.git",
41
+ "ref": "v1.0.0",
42
+ "path": "oats-package"
43
+ },
39
44
  "oats.framework": {
40
45
  "url": "https://github.com/awebai/oats.git",
41
- "ref": "oats-framework/v1.7.0",
46
+ "ref": "oats-framework/v1.8.0",
42
47
  "path": "oats-package"
43
48
  }
44
49
  },
@@ -71,6 +76,8 @@
71
76
  "oats.engineering-expert": "oats.engineering",
72
77
  "oats.developer": "oats.engineering",
73
78
  "oats.code-review": "oats.engineering",
74
- "oats.maintainer": "oats.engineering"
79
+ "oats.maintainer": "oats.engineering",
80
+ "oats.folio": "oats.apps",
81
+ "oats.library": "oats.apps"
75
82
  }
76
83
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.47.0",
3
+ "version": "0.48.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -60,7 +60,7 @@ members:
60
60
  - git:github.com/acme/agents # the host is a member too
61
61
  - git:github.com/acme/platform
62
62
  packages:
63
- oats.framework: v1.7.0 # bare versions resolve through the official catalog
63
+ oats.framework: v1.8.0 # bare versions resolve through the official catalog
64
64
  oats.okf: v4.1.1
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }