@awebai/oats 0.69.22 → 0.69.23
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 +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +60 -17
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +117 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +4 -3
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/deployment-data.mjs +4 -2
- package/packages/client/deployment-panel.mjs +2 -1
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +4 -3
- package/packages/client/workspace-cli.mjs +13 -2
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.23** ([release notes](release-notes/v0.69.23.md)).
|
|
10
|
+
The 0.69.23 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.69.
|
|
14
|
+
0.69.23,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
24
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.23, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.23 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,13 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
|
|
221
|
+
oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
|
|
222
|
+
instances, or move stopped ones with `oats instance upgrade`, to take the
|
|
223
|
+
board teaching and the mail read. `--same-work` and `oats instance
|
|
224
|
+
same-work` are deprecated aliases of `--related-work` and `oats instance
|
|
225
|
+
related-work`. A team image that ran the experimental
|
|
226
|
+
bb image is rebuilt, with the bb image from oats-project/oats-bb.
|
|
220
227
|
- **[0.69.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
|
|
221
228
|
oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
|
|
222
229
|
The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ 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.
|
|
58
|
-
oats.okf: v6.
|
|
57
|
+
oats.framework: v1.27.0 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v6.3.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
package/lib/argv.mjs
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Dependency-free. */
|
|
5
5
|
|
|
6
6
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
7
|
-
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
|
|
7
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "board", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "related-work", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
|
|
8
8
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
9
9
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
10
10
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -16,8 +16,12 @@ const INLINE_TEXT_FLAGS = new Set(["message"]);
|
|
|
16
16
|
/** Free-text flags whose inline value is always kept whole, the empty one included:
|
|
17
17
|
* `--description=` clears a trigger's or schedule's description. */
|
|
18
18
|
const INLINE_WHOLE_FLAGS = new Set(["description"]);
|
|
19
|
+
/** A word that is a switch everywhere but one form, where it takes a value: `oats instance board ask
|
|
20
|
+
* --clear <id>` (feature instance-board). There, `--clear=<id>` is `--clear <id>`. */
|
|
21
|
+
const VALUE_IN_FORM = [{ words: ["instance", "board", "ask"], name: "clear" }];
|
|
19
22
|
export function expandInlineValues(argv) {
|
|
20
23
|
const out = [];
|
|
24
|
+
const valued = new Set(VALUE_IN_FORM.filter((f) => f.words.every((w, i) => argv[i] === w)).map((f) => f.name));
|
|
21
25
|
const inline = new Map();
|
|
22
26
|
let problem;
|
|
23
27
|
for (const a of argv) {
|
|
@@ -25,7 +29,7 @@ export function expandInlineValues(argv) {
|
|
|
25
29
|
if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
|
|
26
30
|
const name = a.slice(2, eq), value = a.slice(eq + 1);
|
|
27
31
|
if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
|
|
28
|
-
problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
|
|
32
|
+
problem ??= KERNEL_SWITCHES.has(name) && !valued.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
|
|
29
33
|
out.push(`--${name}`, value);
|
|
30
34
|
}
|
|
31
35
|
return { argv: out, problem, inline };
|
|
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
|
|
|
181
181
|
* declaration may not cover them: these exact names, and every exact name
|
|
182
182
|
* starting with one of these prefixes (the events log; the stop, restart and
|
|
183
183
|
* start receipts and locks; the rollback marker; AGENTS.md backups; the
|
|
184
|
-
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the
|
|
184
|
+
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the related-work flag, `.oats-related-work.json`, and `.oats-same-work.json`, the file of the same-work flag it replaced, which the kernel still reads while the new one is absent; the agent's board, `.oats-board.json`, and its lock). This is the one list: a new kernel-written top-level
|
|
185
185
|
* home entry MUST be added here and to the `not` patterns of
|
|
186
186
|
* `retirement.disposable.home` in docs/capability-manifest.schema.json. A
|
|
187
187
|
* prefix declaration can reach none of them except through `.oats-`, which is
|
|
188
188
|
* refused whole; `.oats-<provider>` as an exact name stays declarable. */
|
|
189
189
|
const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
|
|
190
|
-
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work"];
|
|
190
|
+
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work", ".oats-related-work", ".oats-board"];
|
|
191
191
|
|
|
192
192
|
/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
|
|
193
193
|
* name or prefix), "kernel-owned", or undefined when it is sound. */
|
package/lib/command-flags.mjs
CHANGED
|
@@ -6,8 +6,28 @@
|
|
|
6
6
|
* missing here is not checked. Kernel-private, not exported from `./core`. Dependency-free. */
|
|
7
7
|
|
|
8
8
|
export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
|
|
9
|
+
/** The spellings the related-work rename (feature instance-related-work) kept as deprecated aliases
|
|
10
|
+
* (feature instance-same-work, the compatibility layer): `oats spawn … --same-work` is `--related-work`,
|
|
11
|
+
* and `oats instance same-work` is `oats instance related-work`. Each use prints its line on stderr, once,
|
|
12
|
+
* before the command runs or is sent to a --server host (sameWorkDeprecation, the dispatch's), and never
|
|
13
|
+
* in a --json answer. spawnInstance's `sameWork` option is the same alias (lib/core.mjs). */
|
|
14
|
+
export const SAME_WORK_ALIASES = Object.freeze({
|
|
15
|
+
flag: "--same-work is renamed: use --related-work",
|
|
16
|
+
verb: "oats instance same-work is renamed: use oats instance related-work",
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** spawnInstance's deprecated option, said as a DeprecationWarning (code OATS_SAME_WORK) by lib/core.mjs. */
|
|
20
|
+
export const SAME_WORK_OPTION_RENAMED = "sameWork is renamed: use relatedWork";
|
|
21
|
+
|
|
22
|
+
/** The deprecation line `argv` (the CLI's argv, after `oats`, as typed) earns by an alias of
|
|
23
|
+
* SAME_WORK_ALIASES, or undefined. */
|
|
24
|
+
export function sameWorkDeprecation(argv) {
|
|
25
|
+
if (argv[0] === "instance" && argv[1] === "same-work") return SAME_WORK_ALIASES.verb;
|
|
26
|
+
if (argv[0] === "spawn" && argv.some((a) => a === "--same-work" || a.startsWith("--same-work="))) return SAME_WORK_ALIASES.flag;
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
9
29
|
export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
|
|
10
|
-
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
30
|
+
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
11
31
|
export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
12
32
|
export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
|
|
13
33
|
export const TEAMS_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]";
|
|
@@ -38,6 +58,16 @@ const waiting = (verb) => ({ command: `instance waiting ${verb}`, operands: [],
|
|
|
38
58
|
usage: `usage: oats instance waiting ${verb} --producer <id>${verb === "set" ? " --reason permission|question|attention" : ""} [--message=<text>] [--home <abs>] [--dir <d>] [--json]` });
|
|
39
59
|
const ATTENTION_USAGE = "usage: oats instance attention [--message=<text>] [--clear] [--json]";
|
|
40
60
|
const attentionHasNo = (flag) => `oats instance attention has no ${flag}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${ATTENTION_USAGE}`;
|
|
61
|
+
/** `oats instance board`'s forms (feature instance-board), each its own usage line; BOARD_USAGE all of them. */
|
|
62
|
+
const BOARD_FORMS = Object.freeze({
|
|
63
|
+
set: "oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]",
|
|
64
|
+
unset: "oats instance board unset <key> [--json]",
|
|
65
|
+
ask: "oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json] | oats instance board ask --clear <id> [--json]",
|
|
66
|
+
});
|
|
67
|
+
export const BOARD_USAGE = `usage: ${Object.values(BOARD_FORMS).join(" | ")}`;
|
|
68
|
+
/** `oats instance board` records on the instance it runs in, as `attention` does: these are refused in its words. */
|
|
69
|
+
const boardRefused = (verb) => Object.freeze(Object.fromEntries(["--home", "--dir", "--server"].map((f) => [f, `oats instance board has no ${f}: it records on the board of the instance it runs in ($OATS_INSTANCE_HOME); usage: ${BOARD_FORMS[verb]}`])));
|
|
70
|
+
const board = (verb, operand, values, required = 1) => ({ command: `instance board ${verb}`, operands: [operand], required, values, switches: ["--json"], refused: boardRefused(verb), usage: `usage: ${BOARD_FORMS[verb]}` });
|
|
41
71
|
const TRIGGER_RUN_SOURCE = Object.freeze(["--run-source", "--json"]);
|
|
42
72
|
const SESSION_ADDRESS = Object.freeze(["--home", "--instance", "--server"]);
|
|
43
73
|
/** Every `oats session` form refuses the captured path's selector in these words (bin's sessionCmd says them
|
|
@@ -82,7 +112,7 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
82
112
|
{ command: "spawn", operands: ["soul"],
|
|
83
113
|
values: ["--agents-root", "--backend", "--base", "--branch", "--dir", "--expect-decision", "--harness", "--herdr-socket", "--idempotency-key", "--instance", "--launch-config", "--max-age", "--model", "--name", "--parent", "--provider", "--purpose", "--relation", "--relative-root", "--relative-to", "--repo", "--runtime", "--server", "--task", "--task-file", "--trigger-event", "--wake-cron", "--wake-every", "--wake-file", "--wake-json", "--wake-message", "--wake-message-file", "--wake-tz", "--work", "--work-dir"],
|
|
84
114
|
arity: { "--provider": 2 },
|
|
85
|
-
switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--same-work", "--suggest-name", "--yolo"],
|
|
115
|
+
switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--related-work", "--same-work", "--suggest-name", "--yolo"],
|
|
86
116
|
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
87
117
|
// repository's souls/<name>, so spawn never writes one.
|
|
88
118
|
refused: { "--instructions-file": SPAWN_REMOVED_SOUL("--instructions-file"), "--def-file": SPAWN_REMOVED_SOUL("--def-file"),
|
|
@@ -103,11 +133,18 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
103
133
|
usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
104
134
|
onOff("background"),
|
|
105
135
|
onOff("pin"),
|
|
136
|
+
onOff("related-work"),
|
|
137
|
+
// The verb's deprecated alias (SAME_WORK_ALIASES): the same arguments.
|
|
106
138
|
onOff("same-work"),
|
|
107
139
|
waiting("set"),
|
|
108
140
|
waiting("clear"),
|
|
109
141
|
{ command: "instance attention", operands: [], values: ["--message"], switches: ["--clear", "--json"],
|
|
110
142
|
refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
|
|
143
|
+
board("set", "key", ["--label", "--value", "--unit", "--link"]),
|
|
144
|
+
board("unset", "key", []),
|
|
145
|
+
// `--clear <id>` takes the id as its value, so the question is optional here; the command refuses a form
|
|
146
|
+
// with neither, or with both.
|
|
147
|
+
board("ask", "question", ["--option", "--id", "--context-file", "--clear"], 0),
|
|
111
148
|
{ command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
|
|
112
149
|
refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
|
|
113
150
|
usage: "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
|
package/lib/core.mjs
CHANGED
|
@@ -48,7 +48,7 @@ import { createHash, randomUUID } from "node:crypto";
|
|
|
48
48
|
import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
|
|
49
49
|
import { sameDirectory } from "../packages/record/lib/directory-identity.mjs";
|
|
50
50
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
51
|
-
import { RETIRE_DELETE_BRANCH_REFUSED } from "./command-flags.mjs";
|
|
51
|
+
import { RETIRE_DELETE_BRANCH_REFUSED, SAME_WORK_OPTION_RENAMED } from "./command-flags.mjs";
|
|
52
52
|
import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
|
|
53
53
|
import { AGENT_PANE_OPTION, inspectSessionTarget, inputSessionTarget, resolveAgentPane } from "./session-input.mjs";
|
|
54
54
|
import { RETIRE_HOOK_WARNING_KIND, appendEvent, incarnationOf, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
|
|
@@ -99,7 +99,8 @@ import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPla
|
|
|
99
99
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
100
100
|
import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
|
|
101
101
|
import { PIN_FILE } from "./instance-pin.mjs";
|
|
102
|
-
import {
|
|
102
|
+
import { BOARD_FILE, BOARD_LOCK } from "./instance-board.mjs";
|
|
103
|
+
import { RELATED_WORK_FILE, SAME_WORK_FILE, relatedWorkBinding, writeRelatedWork } from "./instance-related-work.mjs";
|
|
103
104
|
import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
|
|
104
105
|
import { thisBoot } from "./session-seen.mjs";
|
|
105
106
|
import { FRESH_REASON, RESUME_WAITING, SESSION_END } from "./session-resume-contract.mjs";
|
|
@@ -3683,7 +3684,13 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3683
3684
|
if (relation === "unrelated" && relativeTo) throw new Error(`relation "unrelated" takes no relativeTo`);
|
|
3684
3685
|
if (relation && relation !== "unrelated" && !relativeTo) throw new Error(`relation "${relation}" needs a relative-to instance`);
|
|
3685
3686
|
if (typeof o.relativeRoot === "string" && o.relativeRoot.trim() && !relativeTo && !legacyParent) throw new Error(`relativeRoot only qualifies relativeTo/parent`);
|
|
3687
|
+
if (o.relatedWork !== undefined && typeof o.relatedWork !== "boolean") throw oatsError("E_BAD_ARGS", "relatedWork must be true or false");
|
|
3688
|
+
// `sameWork`, the option's old name, is an alias (the related-work compatibility layer): either sets the flag.
|
|
3689
|
+
// Its use is said once per call as Node's DeprecationWarning (stderr, never an answer); the CLI passes
|
|
3690
|
+
// `relatedWork`, its own alias having said so already (lib/command-flags.mjs SAME_WORK_ALIASES).
|
|
3686
3691
|
if (o.sameWork !== undefined && typeof o.sameWork !== "boolean") throw oatsError("E_BAD_ARGS", "sameWork must be true or false");
|
|
3692
|
+
if (o.sameWork !== undefined) process.emitWarning(SAME_WORK_OPTION_RENAMED, { type: "DeprecationWarning", code: "OATS_SAME_WORK" });
|
|
3693
|
+
const relatedWorkAsked = o.relatedWork === true || o.sameWork === true;
|
|
3687
3694
|
if (!relation && legacyParent) { relation = "child"; relativeTo = legacyParent; }
|
|
3688
3695
|
if (relation === "unrelated") { relation = undefined; relativeTo = undefined; }
|
|
3689
3696
|
|
|
@@ -3814,11 +3821,12 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3814
3821
|
if (anchorMeta?.siblingInstance) siblingInstance = anchorMeta.siblingInstance;
|
|
3815
3822
|
}
|
|
3816
3823
|
if (!relation && attachedOwner && attachedOwner !== instance) parentInstance = attachedOwner;
|
|
3817
|
-
// Feature instance-
|
|
3818
|
-
// it (child, a sibling of a non-root, --relation parent under a parented anchor, attached)
|
|
3819
|
-
//
|
|
3820
|
-
|
|
3821
|
-
|
|
3824
|
+
// Feature instance-related-work: the flag binds the parent the new home records, whichever relation gave
|
|
3825
|
+
// it (child, a sibling of a non-root, --relation parent under a parented anchor, attached), else the
|
|
3826
|
+
// sibling it records (a sibling of a root or of a root's sibling, --relation parent over an anchor with a
|
|
3827
|
+
// sibling link). Neither: refused here, before any home, worktree or hook, a preview's included.
|
|
3828
|
+
if (relatedWorkAsked && !relatedWorkBinding({ parentInstance: parentInstance !== instance ? parentInstance : undefined, siblingInstance: siblingInstance !== instance ? siblingInstance : undefined })) {
|
|
3829
|
+
throw oatsError("E_BAD_ARGS", `--related-work needs a parent or a sibling: ${instance} would record no parent or sibling instance${relation ? ` (relation ${relation}${relativeTo ? ` to ${relativeTo}` : ""})` : ""}; spawn it with --parent <instance> or --relation sibling --relative-to <instance>, or without --related-work; nothing was spawned`);
|
|
3822
3830
|
}
|
|
3823
3831
|
// K5 §4 — child-spawn permission is ENFORCED here, by the spawn route. The
|
|
3824
3832
|
// parent's recorded policy (instance.json policy.childSpawns) says whether
|
|
@@ -4939,9 +4947,10 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4939
4947
|
Object.assign(meta, workspaceRecord);
|
|
4940
4948
|
}
|
|
4941
4949
|
const spawnWarnings = warnings;
|
|
4942
|
-
// Feature instance-
|
|
4943
|
-
//
|
|
4944
|
-
|
|
4950
|
+
// Feature instance-related-work: bound to the parent the home records, else to its sibling (the one
|
|
4951
|
+
// choice, relatedWorkBinding), written before the launch so that the instance's first status shows it;
|
|
4952
|
+
// the home's removal on a rollback takes it with the rest.
|
|
4953
|
+
if (relatedWorkAsked && relatedWorkBinding(meta)) writeRelatedWork(home, relatedWorkBinding(meta));
|
|
4945
4954
|
|
|
4946
4955
|
spawnTmux = meta.tmux;
|
|
4947
4956
|
if (work === "directory") assertDirectoryRoots(home, homeReal);
|
|
@@ -5476,13 +5485,15 @@ function retireGitProbe(repo, args, { encoding } = {}) {
|
|
|
5476
5485
|
* KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
|
|
5477
5486
|
// `.oats-color.json` (feature instance-color) and `.oats-background.json` (feature instance-background) are
|
|
5478
5487
|
// presentation anyone may change at any time: never work. `.oats-pinned.json` (feature instance-pin) is
|
|
5479
|
-
// presentation of the same kind.
|
|
5480
|
-
// `.oats-
|
|
5488
|
+
// presentation of the same kind. `.oats-board.json` (feature instance-board) is the agent's own display, and
|
|
5489
|
+
// `.oats-board.lock` what a write killed while it held the lock leaves: never work.
|
|
5490
|
+
// `.oats-related-work.json` (feature instance-related-work) is kernel presentation of the same kind, and so is
|
|
5491
|
+
// `.oats-same-work.json`, the file of the flag it replaced: read while the new one is absent, never written.
|
|
5481
5492
|
// `.oats-start-exited` (lib/session-end.mjs) is the window's record of how the harness ended: every
|
|
5482
5493
|
// launched home whose harness ever ended holds it.
|
|
5483
5494
|
// `.oats-start-env.json` and its key (lib/start-env.mjs) are written at every start that renders a
|
|
5484
5495
|
// recipe, after the spawn's baseline: every launched home holds them.
|
|
5485
|
-
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5496
|
+
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, BOARD_FILE, BOARD_LOCK, RELATED_WORK_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5486
5497
|
// `instance.json.tmp-<pid>` is what a process killed between the two steps of writeJsonAtomic leaves
|
|
5487
5498
|
// of the record: not a hidden name, so a capability cannot declare it (disposableHomeRootProblem).
|
|
5488
5499
|
const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/, /^instance\.json\.tmp-\d+$/, START_ENV_TMP, LAUNCH_ENV_HANDOFF];
|
|
@@ -9559,7 +9570,7 @@ const claimCommand = (action) => action === "resume" ? "oats session start --res
|
|
|
9559
9570
|
/** What each verb that meets a held claim says it did not do: the words its refusals end with,
|
|
9560
9571
|
* before any effect. After a takeover ended a dead holder's step, every verb says the same
|
|
9561
9572
|
* (lib/errors.mjs nothingAfter). */
|
|
9562
|
-
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance
|
|
9573
|
+
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance related-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
|
|
9563
9574
|
|
|
9564
9575
|
/** The refusals of `arriving` ("retire", "stop", "upgrade", "resume", "start", or "worktree add", which
|
|
9565
9576
|
* reads the claim and does not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
|