@awebai/oats 0.50.0 → 0.51.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, processScanInformation, 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, RETIRE_SELECTED_HOME, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
33
+ findInstanceHome, findInstanceHomes, processScanInformation, 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, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, 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 {
@@ -98,7 +98,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]
98
98
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
99
99
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
100
100
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
101
- const KERNEL_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", "server-probe-features", "worktree-event", "trigger-sources"];
101
+ const KERNEL_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", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key"];
102
102
  /** Commands `--server <id>` runs on a registered server. */
103
103
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
104
104
  const flag = (name) => {
@@ -2874,27 +2874,42 @@ function retireCmd() {
2874
2874
  // resolved the home). A guarded apply acts on the children of the plan it
2875
2875
  // revalidated; a plain or --self retire computes them as the plan does, and
2876
2876
  // passes none when there are none.
2877
- let replayPath = null, plannedExtraWorktrees, fresh, children;
2877
+ let replayPath = null, fresh, revalidate, stalePlan, planFailure;
2878
2878
  if (planRev !== undefined) {
2879
2879
  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
2880
2880
  // Replay first: after a successful retire the home is gone, so the receipt
2881
2881
  // (beside the instances dir, keyed by the idempotency key) is the answer.
2882
2882
  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; } };
2883
2883
  for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
2884
- 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); }
2885
- replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
2886
- // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
2887
- // move or remove one that no longer reads that way when it gets to them.
2888
- plannedExtraWorktrees = fresh.facts.extraWorktrees;
2889
- 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`);
2890
- children = fresh.facts.children;
2884
+ // Before the claim, only the home: where the receipt goes, and the answers of a name that
2885
+ // resolves to no home, to several or to another one.
2886
+ let target;
2887
+ try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2888
+ replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
2889
+ // The plan the revision is checked against is read once, by retireInstance, when it holds the
2890
+ // home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
2891
+ // the state the retire starts from. Against another retire of this home the answer is that one
2892
+ // is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
2893
+ // refused there, and nothing was done. What the retire takes from the plan: its children, and
2894
+ // its extra trees as it names them (the retire refuses as stale rather than move or remove one
2895
+ // that no longer reads that way when it gets to them).
2896
+ revalidate = () => {
2897
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
2898
+ if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
2899
+ return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
2900
+ };
2891
2901
  } else {
2892
- const recorded = descendantsOf(root, name);
2893
- if (recorded.length) children = recorded;
2902
+ // A plain or --self retire reads its recorded children the same way: under the claim, as they
2903
+ // are when the retire starts (an earlier retire that kept the home has repaired lineage by
2904
+ // then), and none when there are none.
2905
+ revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
2894
2906
  }
2895
2907
  let r;
2896
- 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 } : {}) }); }
2908
+ try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
2897
2909
  catch (e) {
2910
+ // The plan could not be read, or its revision is not the one shown: the answers they always had.
2911
+ if (e === planFailure) return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message);
2912
+ if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2898
2913
  if (!e?.code) throw e;
2899
2914
  // A child still running (or whose stop could not be established) refused the retirement: the
2900
2915
  // guarded apply returns the plan it acted on, and the text names each child's reason.
@@ -3224,7 +3239,9 @@ async function sessionCmd() {
3224
3239
  let result;
3225
3240
  if (args[1] === "attach") {
3226
3241
  if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
3227
- process.exitCode = await attachInstanceSession(home);
3242
+ // --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
3243
+ // status 20. Without it every key reaches the agent and there is no keyboard exit.
3244
+ process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
3228
3245
  return;
3229
3246
  }
3230
3247
  if (args[1] === "inspect") result = inspectInstanceSession(home);
@@ -3264,7 +3281,7 @@ async function sessionCmd() {
3264
3281
  const file = flag("file");
3265
3282
  if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
3266
3283
  result = uploadAttachment({ file, home: home === true ? undefined : home });
3267
- } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3284
+ } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3268
3285
  if (JSON_MODE) jsonOk(result);
3269
3286
  else {
3270
3287
  console.log(JSON.stringify(result, null, 2));
@@ -4091,8 +4108,14 @@ async function serverRouteCmd() {
4091
4108
  return;
4092
4109
  }
4093
4110
  if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
4111
+ // --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
4112
+ // probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
4113
+ // once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
4114
+ // would replace the relayed status with 131. Held from here until this process exits.
4115
+ const detachKey = valueFlag("detach-key");
4116
+ if (detachKey !== undefined) process.on("SIGQUIT", () => {});
4094
4117
  let route;
4095
- try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
4118
+ try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
4096
4119
  // ssh failing before the viewer (the version probe, a name resolved through the host's roster)
4097
4120
  // is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
4098
4121
  // and an ssh that never started (no link can come back), exits 1.
@@ -4102,7 +4125,7 @@ async function serverRouteCmd() {
4102
4125
  // ssh exits 255 for its own failures: a link that died under the viewer
4103
4126
  // (keepalives unanswered, the master or the host's sshd gone), or one
4104
4127
  // never made. Say what is known rather than ending silently.
4105
- if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
4128
+ if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
4106
4129
  process.exit(r.status ?? 1);
4107
4130
  }
4108
4131
  // A spawn's argv is checked here, before the server is contacted.
@@ -4386,7 +4409,9 @@ Usage:
4386
4409
  --instance <name> [--json] saved home on its host
4387
4410
  oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
4388
4411
  --instance <name> | --home <abs> remote instance, by its saved route or the server's
4389
- roster (--print shows attach); oats 0.22.2 or later
4412
+ [--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
4413
+ attach --detach-key: as below; the server must
4414
+ advertise session-attach-detach-key
4390
4415
  oats session start --server <id> start a stopped remote instance in its existing home
4391
4416
  --instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
4392
4417
  [--model <m>] [--json] session-start (oats 0.22.9 or later)
@@ -4409,6 +4434,11 @@ Usage:
4409
4434
  [--check] --check: write nothing; report <dir> (~ = this home),
4410
4435
  its state and whether Git reads the workspace remote
4411
4436
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
4437
+ oats session attach --home <absolute-home> [--detach-key <key>]
4438
+ a viewer of one instance. <key> (C-<letter>, M-<letter
4439
+ or digit>, F1 to F12; 'C-\\' is the suggested one)
4440
+ leaves it with exit status 20; without one no key
4441
+ leaves it: every key goes to the agent
4412
4442
  oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
4413
4443
  enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
4414
4444
  tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
@@ -205,8 +205,9 @@ A self-contained package has an `oats.json`:
205
205
  Whether the process exists is the operating system's answer (`kill -0`:
206
206
  "no such process" is gone, another user's process exists), the same on
207
207
  every host. Only then is its start time read: from `/proc`, or with `ps`
208
- (in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
209
- as on macOS. A start that cannot be read is never taken to mean the process is
208
+ where there is no `/proc`, as on macOS: the system `ps`, from
209
+ `/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
210
+ `TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
210
211
  gone, nor shown as alive: `oats status` shows the quarantine
211
212
  (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
212
213
  refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
@@ -43,7 +43,7 @@ see the [official catalog](official-catalog.md) for current pins.
43
43
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
44
44
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
- "server-probe-features","worktree-event"],
46
+ "server-probe-features","worktree-event","session-attach-detach-key"],
47
47
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
48
48
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
49
49
  "capabilityShowApi":1}
@@ -119,6 +119,7 @@ see the [official catalog](official-catalog.md) for current pins.
119
119
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
120
120
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
121
121
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
122
+ | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
122
123
 
123
124
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
124
125
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -3234,7 +3235,8 @@ A first retire prints the **raw receipt**, not an envelope:
3234
3235
  `capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
3235
3236
  - A deferred self-retire (`--self`) prints `{retired, agent, deferred: true,
3236
3237
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
3237
- `{…, alreadyScheduled: true, requestedAt}`.
3238
+ `{…, alreadyScheduled: true, requestedAt}` while one is scheduled and its
3239
+ completion has not started (below).
3238
3240
 
3239
3241
  **Recorded children**, on every apply (plain, guarded and `--self`), as the
3240
3242
  plan says: each child the plan lists is stopped first (bounded SIGTERM,
@@ -3259,12 +3261,96 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
3259
3261
  `--idempotency-key` together.
3260
3262
  - A used key replays its receipt as an **envelope** with `replayed: true`
3261
3263
  (receipts live beside the instances directory and outlive the home).
3262
- - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
3264
+ - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`. That
3265
+ plan is read once, when the retire holds the home's claim (below): it is
3266
+ the state the retire starts from, and one apply appends one
3267
+ `retire-planned` event. Against a retire in flight or a scheduled
3268
+ self-retire the answer is `E_LIFECYCLE_BUSY` and no plan is read, whatever
3269
+ the plan would read by then: a retire in flight has usually changed it (it
3270
+ stops the session of a launched instance before its hooks run). Before the
3271
+ claim an apply only replays a used key and resolves the home
3272
+ (`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`).
3263
3273
  - The children stopped are those of the revalidated plan, and a refusal
3264
3274
  carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
3265
3275
  - A first guarded retire prints the raw receipt with `planRevision`,
3266
3276
  `idempotencyKey` and `replayed: false`.
3267
3277
 
3278
+ **One retire of a home at a time** (0.51.0, #863). Every retire that applies (plain,
3279
+ guarded, `--self` and its detached completion; with `--server`, on the host)
3280
+ holds the home's claim,
3281
+ `<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
3282
+ has resolved the home until it ends, by success or by any refusal or failure.
3283
+ The claim is a file that names its holder by pid and start time. It lies
3284
+ beside the homes, never inside one: a home's bytes are what its retire
3285
+ observes, copies and removes. A second retire of that home does not wait: it
3286
+ answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
3287
+ message), before it stops a session or a child, writes a recovery, runs a
3288
+ hook or changes a file of the home. **`--force` does not bypass it**, and
3289
+ `--plan` takes no claim and refuses nothing new. A guarded apply answers it
3290
+ before `E_PLAN_STALE`: under the claim the answers come in this order: the
3291
+ home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
3292
+ (`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
3293
+ died, for example a retire killed while its hooks ran, is taken over by the
3294
+ next retire of that name. So a killed retire can always be run again. The
3295
+ claim does not end what the killed retire left running: one of its retire
3296
+ hooks may still be running when the next retire takes the claim over and
3297
+ runs the hooks again (#865). Until
3298
+ that name is retired again its claim file stays where it is, and it is safe
3299
+ to remove once its pid is gone. A retire that ends removes its claim file;
3300
+ the `claims/` directory itself stays, empty.
3301
+
3302
+ `details` is `{instance, home, lock, pid, since}`: `lock` is the file that
3303
+ names the holder, `since` when the holder took it. Every message is one
3304
+ line and says that nothing was done:
3305
+
3306
+ - A live holder: `a retire of <name> is already running (pid <pid>, since
3307
+ <at>); nothing was done — wait for it to finish`.
3308
+ - A holder whose start time cannot be read (where `ps` fails, or a claim
3309
+ that records none) is never taken for gone, and its claim is never taken
3310
+ over. `details.unknown` is the reason. The message names the pid, its
3311
+ recorded start, the reason and the way out: check that pid by hand, and if
3312
+ it is not an `oats retire`, remove `<lock>`, then retry.
3313
+ - A claim file that is not a readable claim is never removed. `details` is
3314
+ `{instance, home, lock}`; the message names the file and says to inspect
3315
+ it and remove it if no `oats retire` holds it.
3316
+ - The retire's own start time cannot be read, so it could not hold the claim
3317
+ verifiably: `details` is `{instance, home, lock}`, and the message gives
3318
+ the reader's own reason (the `/proc` read, or what `ps` answered).
3319
+
3320
+ A scheduled self-retire counts from the moment it is scheduled. Its pending
3321
+ marker (`pendingMarker`) records the completion process as `completionPid`
3322
+ and `completionStart` (`null` when the start could not be read). While that
3323
+ process lives, every other retire of the instance is refused the same way,
3324
+ `--self --keep-dir` included: `a retire of <name> is already scheduled (its
3325
+ completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
3326
+ for it to finish`, with `details.lock` the pending marker, `details.pid` the
3327
+ completion and `details.since` the marker's `requestedAt`. A completion
3328
+ whose start cannot be read is refused as a holder's is (`details.unknown`),
3329
+ the file to remove being the pending marker. A second `--self` answers
3330
+ `alreadyScheduled: true` only while the completion has not started. While
3331
+ the first `--self` is still scheduling, or once the completion holds the
3332
+ claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
3333
+ retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
3334
+ left its outcome at `resultPath` (it failed) or is gone (it died), nor when
3335
+ it names no completion (a marker written before 0.51.0): `oats retire
3336
+ <instance>` then retries the retirement, as before. The completion waits up
3337
+ to 3 s for the retire that scheduled it to release the claim, then takes it
3338
+ as any retire does; one that meets another retire still running is refused,
3339
+ and records that at `resultPath` like any failed completion.
3340
+
3341
+ The home is resolved again once the claim is held. One that another retire
3342
+ removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
3343
+ instance does. If the name is by then the home of another agent, the retire
3344
+ starts over on that home, under that home's claim; after two such changes it
3345
+ answers `E_LIFECYCLE_BUSY` (`the home of <name> changed while its claim was
3346
+ being taken …; nothing was done — retry`, `details: {instance, home, lock}`).
3347
+ A retire of a name that has no home also removes a claim of that name whose
3348
+ holder is gone, left by a retire that was killed after it removed the home.
3349
+
3350
+ The claim orders retires only. `oats instance stop`, `oats session start`
3351
+ and `oats worktree add` do not take it and are not refused by it, and `oats
3352
+ status` does not show a held claim (#866).
3353
+
3268
3354
  Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
3269
3355
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
3270
3356
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
@@ -3273,7 +3359,9 @@ message names the entry or the state that could not be read, or the directory
3273
3359
  Git reads as the top level of a `work/` whose `core.worktree` names another
3274
3360
  one),
3275
3361
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
3276
- `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
3362
+ `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
3363
+ home is running or scheduled, `--force` included: one retire of a home at a
3364
+ time, above; or, feature
3277
3365
  `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3278
3366
  row with `spawnInProgress: true`, `--force` included; or one whose start time
3279
3367
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
@@ -346,8 +346,9 @@ positive whole number of milliseconds replaces the fixed 30-minute timeout of
346
346
  tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
347
347
  10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
348
348
  the kernel read a process's start time with `ps`, as on a host without
349
- `/proc` (macOS), on a host that has it. A launch configuration cannot set
350
- any of them. Do not set them in a deployment.
349
+ `/proc` (macOS), on a host that has it; an absolute path instead runs that
350
+ file as `ps`, directly and in the same fixed environment; any other value
351
+ reads no start at all. A launch configuration cannot set any of them. Do not set them in a deployment.
351
352
 
352
353
  **An instance creates an agents' session or window without its own
353
354
  environment.** Nothing of an instance's environment reaches a server or a
@@ -777,6 +778,7 @@ stopped ([missing socket file](#missing-socket)).
777
778
  oats session inspect --home /abs/home --json
778
779
  oats session input --home /abs/home --text-file message.txt --json
779
780
  oats session attach --home /abs/home
781
+ oats session attach --home /abs/home --detach-key 'C-\'
780
782
  ```
781
783
 
782
784
  - **inspect** reports `backend`, `present` and `state`: `unknown` for a live
@@ -826,6 +828,89 @@ oats session attach --home /abs/home
826
828
  session linked to the agent's window alone.
827
829
  Closing the viewer leaves the agent running.
828
830
 
831
+ **Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
832
+ every key goes to the agent, the tmux prefix included. Close the terminal.
833
+ With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
834
+ `session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
835
+ viewer's client. The agent's window and every other viewer are untouched.
836
+ The key is taken from the agent's input: the agent never receives it while
837
+ this viewer is attached. A keyed viewer reads a tmux key table of its own,
838
+ named as its temporary session and removed with it, so the key is bound
839
+ for that viewer alone. Check the feature in `oats version --json` before
840
+ passing the flag: a kernel without it ignores the flag and opens a viewer
841
+ with no exit.
842
+
843
+ The key is one of these, spelled exactly (case-sensitive):
844
+
845
+ ```
846
+ key = control / meta / function
847
+ control = "C-" ( "a"-"g" / "j"-"l" / "n"-"z" / "\" / "]" / "^" / "_" )
848
+ meta = "M-" ( "a"-"z" / "0"-"9" )
849
+ function = [ "C-" / "M-" / "S-" ] "F" ( "1" … "12" )
850
+ ```
851
+
852
+ Anything else is `E_BAD_ARGS`, before any tmux or ssh call: a missing
853
+ value, a plain character, `C-i` and `C-m` (Tab and Enter on tmux before
854
+ 3.5), `C-h` (the byte, 0x08, that many terminals send for Ctrl+Backspace
855
+ and some for Backspace, so the name is not one key everywhere), `C-[`
856
+ (Escape), `M-[`, `M-]`, `M-\`, `M-O` and the other ESC + C1 introducers (a
857
+ terminal reply can arrive as that key), `Any`, mouse key names, two keys,
858
+ upper case, and anything with a space, `;` or a control character. The
859
+ kernel does not judge whether a harness reads the key: that is the
860
+ caller's choice.
861
+
862
+ **While the pane is scrolled back.** The viewer's wheel and drag bindings
863
+ put the pane in tmux's copy mode, and there copy mode's key table is read
864
+ before the viewer's. A detach key that copy mode binds acts in copy mode
865
+ and does not detach; it detaches once the mode is left (`q`, or scrolling
866
+ back to the bottom). The grammar does not exclude those keys. The
867
+ copy-mode tables are the tmux server's, shared by every session and
868
+ changed by the operator's `~/.tmux.conf`, so no grammar can promise a key
869
+ is free there, and the kernel never binds a detach key in a table other
870
+ sessions read. With tmux's default tables (3.7c), 35 of the 111 keys are
871
+ taken in emacs or vi copy mode (for example `C-e`, `C-c`, `M-w`, `C-u`);
872
+ `C-\` and `F12` are bound in neither and detach from copy mode. Detaching
873
+ while scrolled back leaves the agent's pane in copy mode for the next
874
+ viewer, as closing a viewer mid-scroll does.
875
+
876
+ **The suggested key is `C-\`**, written `--detach-key 'C-\'` (quoted: an
877
+ unquoted trailing backslash continues the line). The kernel fixes no key.
878
+ What was checked:
879
+
880
+ - It has no default binding in Claude Code 2.1.288 (which refuses to let
881
+ a user bind it: "terminal quit signal"), Codex CLI 0.160.0 or pi 1.0.2.
882
+ It is unbound in bash 5.3 (`bind -p`) and in zsh's and fish's documented
883
+ defaults. It is the default detach key of dtach and abduco.
884
+ - A viewer with this key gives up: in a fallback shell, the tty's QUIT (no
885
+ SIGQUIT from the keyboard); in vim and nvim, the `C-\ C-n` prefix; in
886
+ nano, Replace (also on `M-r`).
887
+ - On a layout where `\` needs AltGr, use `F12`: it has no default binding
888
+ in the same three harnesses, bash, nvim or less. Some terminals and
889
+ laptops keep F12 for themselves.
890
+ - `C-]`, `C-_`, `C-g`, `C-t` and `C-b` are each bound by all three
891
+ harnesses.
892
+
893
+ **Exit status.**
894
+
895
+ | How the command ended | Status |
896
+ |---|---|
897
+ | Left by the detach key (the agent keeps running) | 20 |
898
+ | The viewer ended without the key: the agent's window ended, or `oats` itself was stopped by SIGHUP, SIGTERM or SIGINT and closed the viewer | 0 |
899
+ | A refusal (bad arguments, not launched, session gone), or tmux failing under the viewer (its server exited) | 1 |
900
+
901
+ 20 is answered only when the key's own binding ran, and only by a kernel
902
+ with the feature. No status an existing caller sees changes meaning. 20 is
903
+ nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
904
+ treat a leave by the key as a failure. The routed form (`--server`) relays
905
+ these statuses and adds ssh's own 255 ([servers.md](servers.md#run-there)).
906
+
907
+ With `--detach-key`, `oats` handles SIGQUIT. `C-\` is also the terminal's
908
+ QUIT character: pressed before the viewer has the terminal, or again once
909
+ the viewer has given it back, it would otherwise end `oats` with status 131
910
+ and leave the viewer's session and key table on the tmux server. A QUIT
911
+ that arrives before the key was used stops the attach, with status 1;
912
+ after a leave by the key it changes nothing, and the status is 20.
913
+
829
914
  ### Attachments
830
915
 
831
916
  `oats session upload --file <local> --home <abs>` copies a file into
@@ -65,6 +65,7 @@ published to npm. Its developer docs are in
65
65
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
66
66
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
67
67
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
68
+ | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`) and by `oats retire` per home (`core.mjs`, `retireInstance`) |
68
69
  | `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
69
70
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
70
71
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
@@ -387,6 +388,13 @@ and acts on every existing session through its recorded socket
387
388
  `list-windows`, `new-window` (a window id) and `set-option`.
388
389
  - A server a test starts is killed by its socket, never by name and never
389
390
  with a bare `tmux kill-server`.
391
+ - A test that needs a terminal (an attached tmux client, a key press) runs
392
+ the command in a pane of a second private server and types at that pane
393
+ with `send-keys`; the pane's shell records the exit status
394
+ (`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
395
+ bytes a terminal sends (`send-keys -l`). A pane program that must show the
396
+ keys it reads puts its terminal in raw mode first: in cooked mode a control
397
+ byte is a signal or an edit, not input.
390
398
 
391
399
  Nor does a test depend on where or how the suite runs:
392
400
 
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.0.0
44
- oats.aweb: v1.21.1
43
+ oats.okf: v5.0.1
44
+ oats.aweb: v1.24.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.0**. Provider implementation and
9
+ This is the operator guide for **oats.okf 5.0.1**. Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
23
23
  ```yaml
24
24
  # oats-workspace.yaml (excerpt)
25
25
  packages:
26
- oats.okf: v5.0.0
26
+ oats.okf: v5.0.1
27
27
  defaults:
28
28
  knowledge: { oats.okf: { from: package } }
29
29
  stores:
@@ -105,7 +105,8 @@ explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
105
105
  5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
106
106
  removed keys still refuse and name the fix. The harvester has no provider
107
107
  runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
108
- selection and retires after its handoff.
108
+ selection and retires after successful handoff or nothing promotable. A
109
+ publication failure retains its live home; see [the flow](#the-flow).
109
110
 
110
111
  ## The soul's okf.json
111
112
 
@@ -165,10 +166,22 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
165
166
  notes, edits only owned nodes in its own Git checkout, validates the
166
167
  **whole base**, and creates a normal `okf-harvest`-labelled PR with v2
167
168
  provenance. Proposal text is data written with the native file tool into
168
- commit-message/PR-body files, never shell command text. It reports the PR
169
- and retires rather than waiting for acceptance. If source authority is
170
- unavailable it stops and reports; a consistent instance/soul pair alone
171
- does not prove proposer authorship.
169
+ commit-message/PR-body files, never shell command text. A publication ref
170
+ is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
171
+ name in it; Git validates the full ref and the push must create a new
172
+ ref, never update or adopt an existing one. Source identity stays in
173
+ commit text and PR provenance. After all PRs are open (or nothing is
174
+ promotable), it hands over and retires rather than waiting for acceptance.
175
+ If source authority is unavailable it stops and reports; a consistent
176
+ instance/soul pair alone does not prove proposer authorship.
177
+ **On any publication failure it does not retire:** it keeps the live home,
178
+ clone/any commit, exact error and commit/PR text locations, and notifies
179
+ the source through existing messaging when reachable. Missing or failed
180
+ messaging does not hide the original error or permit retirement. Existing
181
+ attention may expose the blocked home where supported. No automatic
182
+ retries, new recipient or maintainer preflight; a maintainer exists only
183
+ for a labelled PR. A gh error can leave remote effects, so partial or
184
+ uncertain publication is not completion or permission to clean up.
172
185
  4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
173
186
  Human-accepted decisions are not silently superseded; the review path
174
187
  keeps its human gate. A PR is not accepted knowledge until merged.
@@ -9,9 +9,9 @@ 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.9.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.24.0` | `oats.aweb` (messaging) | |
12
+ | `oats.framework` | `oats-framework/v1.9.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.24.1` | `oats.aweb` (messaging) | |
15
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` |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.0.1`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.0 # bare version → the official catalog
47
+ oats.okf: v5.0.1 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.0`, `5.0.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.0.1`, `5.0.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 (`v5.0.0` or `oats-framework/v1.9.0`) and the payload path. An id
54
+ convention (`v5.0.1` or `oats-framework/v1.9.1`) 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.9.0
78
- oats.okf: v5.0.0
79
- oats.aweb: v1.24.0
77
+ oats.framework: v1.9.1
78
+ oats.okf: v5.0.1
79
+ oats.aweb: v1.24.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.0 ✓ (@ 12db7749)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.1 ✓ (@ 96b28d5c)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -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.24.0 # a catalog version
137
+ oats package add oats.aweb v1.24.1 # 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
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.0",
164
- "commit": "12db77492d92154099e7f1aad60a98b1d47f6631",
163
+ "version": "5.0.1",
164
+ "commit": "96b28d5cd4f01e48ed50d8e999e8715749a99e87",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.1", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.9.0`
362
- resolves to tag `oats-framework/v1.9.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.9.1`
362
+ resolves to tag `oats-framework/v1.9.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.