@awebai/oats 0.56.0 → 0.57.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
@@ -2936,7 +2936,7 @@ async function spawnCmd() {
2936
2936
  ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
2937
2937
  // Directory execution uses deployment configuration, not an ambient Git
2938
2938
  // checkout (especially when invoked via --dir from a source instance).
2939
- // An attached instance's repository is its work tree owner's (derived by the kernel).
2939
+ // An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
2940
2940
  repo: preparedRepo !== undefined ? preparedRepo : ["directory", "attached"].includes(requestedWork || agent.work)
2941
2941
  ? repo : repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
2942
2942
  work: requestedWork, workDir, harness: harnessFlag(), backend, yolo, model: flag("model"), branch,
@@ -3090,13 +3090,15 @@ function retireCmd() {
3090
3090
  revalidate = () => {
3091
3091
  try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
3092
3092
  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 } }));
3093
- return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
3093
+ return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
3094
3094
  };
3095
3095
  } else {
3096
3096
  // A plain or --self retire reads its recorded children the same way: under the claim, as they
3097
3097
  // are when the retire starts (an earlier retire that kept the home has repaired lineage by
3098
3098
  // then), and none when there are none.
3099
- revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
3099
+ // The instances the plan lists under `ambiguous` go with them: the retire does not act on
3100
+ // them, and says what it left the ones attached to a tree it moved or removed with.
3101
+ revalidate = () => { const recorded = descendantsOf(root, name); return { ...(recorded.length ? { children: recorded } : {}), ...(recorded.ambiguous?.length ? { ambiguous: recorded.ambiguous } : {}) }; };
3100
3102
  }
3101
3103
  let r;
3102
3104
  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 }); }
@@ -3155,9 +3157,11 @@ function retireCmd() {
3155
3157
  process.exit(1);
3156
3158
  }
3157
3159
  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
3158
- // An attached child the retire repointed to the retained worktree (#718), as its link now reads.
3159
- const followsWorktree = (k) => { if (r.retention?.worktree !== "retained") return false; try { return readlinkSync(join(k.home, "work")) === r.retention.movedTo; } catch { return false; } };
3160
- for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${followsWorktree(k) ? `; its work now links to the retained worktree ${r.retention.movedTo}` : ""}`);
3160
+ // An attached child the retire repointed to a retained worktree, work/ (#718) or an extra tree
3161
+ // (#964), as its link now reads.
3162
+ const retainedAt = [...(r.retention?.worktree === "retained" ? [r.retention.movedTo] : []), ...(r.extraWorktrees || []).filter((t) => t.outcome === "retained").map((t) => t.movedTo)];
3163
+ const followsWorktree = (k) => { try { const to = readlinkSync(join(k.home, "work")); return retainedAt.includes(to) ? to : null; } catch { return null; } };
3164
+ for (const k of r.childrenStopped || []) { const to = followsWorktree(k); console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${to ? `; its work now links to the retained worktree ${to}` : ""}`); }
3161
3165
  // Preserving work and not saying so leaves the operator believing it is gone,
3162
3166
  // which is most of the harm of deleting it. Name the classes and the path.
3163
3167
  for (const line of workRecoveryLines(r)) console.log(line);
@@ -4665,9 +4669,11 @@ Usage:
4665
4669
  oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
4666
4670
  the instances of the workspace of the deployment at or
4667
4671
  above <path> (default: where you are), on this machine
4668
- and on the machines registered here; it changes nothing.
4669
- ? help, w workspaces, q quit. Needs a terminal on stdin and
4670
- stdout and has no --json form; --ascii = ASCII rules and marks
4672
+ and on the machines registered here. Enter opens an agent's
4673
+ terminal; it stops, starts, restarts and retires them after a
4674
+ confirmation. ? help, w workspaces, q quit. Needs a terminal on
4675
+ stdin and stdout and has no --json form; --ascii = ASCII rules
4676
+ and marks
4671
4677
  oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
4672
4678
  --workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
4673
4679
  [--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
@@ -4922,7 +4928,9 @@ Usage:
4922
4928
  again with the same arguments: a no-op; --preview:
4923
4929
  the clone, path, branch, base and hooks, nothing done
4924
4930
  oats worktree remove --purpose <p> [--json] git worktree remove of a tree made by add (a dirty
4925
- tree is refused: E_WORKTREE_DIRTY); the branch is kept
4931
+ tree is refused: E_WORKTREE_DIRTY; so is the work of an
4932
+ attached instance whose session is running or cannot
4933
+ be read: E_CHILDREN_RUNNING); the branch is kept
4926
4934
  oats readiness (--soul <n> | --home <abs>) [--policy] [--json]
4927
4935
  readinessApi 2 for a soul or an instance home:
4928
4936
  installed | configured | member | providers, each
@@ -2542,7 +2542,11 @@ what could not be printed is dropped. Its result:
2542
2542
 
2543
2543
  `remove` answers `{purpose, path, removed: true, rolledBack, branch,
2544
2544
  branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
2545
- `rolledBack` is `false` and `branchKept` is `true`. When it completed an
2545
+ `rolledBack` is `false` and `branchKept` is `true`. When an instance whose
2546
+ session is stopped was [attached](souls-and-instances.md#extra-trees) to the
2547
+ removed tree, `warnings` carries one string for it: `<instance>: its work
2548
+ was <tree>, which was removed; its work link <home>/work now points at a
2549
+ path that is gone`. With no attached instance the answer is what it was. When it completed an
2546
2550
  interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
2547
2551
  whether the branch still exists. The rollback deletes the branch only when
2548
2552
  that add created it, no worktree has it checked out, and it still points at
@@ -2654,6 +2658,7 @@ A failed `add` reports the same facts about its rollback in `details`:
2654
2658
  | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
2655
2659
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2656
2660
  | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
2661
+ | `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
2657
2662
  | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2658
2663
  | `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
2659
2664
 
@@ -4337,7 +4342,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4337
4342
  - of other homes: the children as the plan names them (`instance`,
4338
4343
  `agent`, `home`; a child's agent is the name its soul's file gives),
4339
4344
  the edges that could not be followed (`facts.ambiguous`, whole) and the
4340
- children attached to this home's `work/`.
4345
+ instances attached to this home's `work/` and to each of its extra
4346
+ trees, the recorded children and those of a name that is not unique
4347
+ alike: the plan's notes name them (#964).
4341
4348
 
4342
4349
  A key that is derived is bound through what it is derived from:
4343
4350
  `facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
@@ -4538,6 +4545,32 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4538
4545
  --discard-worktree the worktree is removed and their work link will
4539
4546
  dangle`. It holds for either choice; no other key changes. A relink that
4540
4547
  fails is a string in the receipt's `warnings`.
4548
+ - The note of an extra tree that recorded children are attached to (their
4549
+ `work` is a link to that tree) names them and says what the retire leaves
4550
+ them with. For a tree that would be removed it ends `; attached child
4551
+ instance(s) <names> use it as their work, and their work link would then
4552
+ point at a path that is gone`; for one that would be re-homed, `; attached
4553
+ child instance(s) <names> use it as their work, and the retire repoints
4554
+ their work link to it`. A tree the retire refuses is neither moved nor
4555
+ removed, and its note says nothing of them. Names too long for the note
4556
+ give way to `<n> of the recorded children`. They are strings in `notes`: no
4557
+ key changes. Who is attached to each tree is part of `planRevision`
4558
+ ([what the revision binds](#retire-revision-work)).
4559
+ - The retire does not act on an instance listed under `ambiguous`, and one
4560
+ that is attached to a tree of this home is named with what that leaves it
4561
+ with. An extra tree's note gains a clause of its own, after the one for
4562
+ the recorded children: `; attached instance(s) <names>, listed under
4563
+ ambiguous, use it as their work: the retire does not stop them, and their
4564
+ work link would then point at a path that is gone` for a tree that would
4565
+ be removed, and `…: the retire neither stops them nor repoints their work
4566
+ link, which would then point at a path that is gone (the tree would be at
4567
+ <movedTo>)` for one that would be re-homed. For `work/` it is a note of
4568
+ its own, in a worktree-mode plan: `attached instance(s) <names>, listed
4569
+ under ambiguous, use this home's work/ as their work: the retire neither
4570
+ stops them nor repoints their work link, which will then point at a path
4571
+ that is gone, whether the worktree is retained (the receipt names where)
4572
+ or removed with --discard-worktree`. The note for the recorded children
4573
+ above is unchanged.
4541
4574
  - `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
4542
4575
  (a detached checkout or attached spawn before 0.49.0, #641): it is not a
4543
4576
  branch name, so `facts.work.drift` is `false` for it as well.
@@ -4648,6 +4681,29 @@ A first retire prints the **raw receipt**, not an envelope:
4648
4681
  removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
4649
4682
  nothing happened, answered after the hooks: #895).
4650
4683
  The key is additive.
4684
+ - `warnings` also says what the retire left the attached children of a tree
4685
+ it moved or removed with, one string per child, for `work/` and for each
4686
+ extra tree. A child that could not be repointed to a retained tree:
4687
+ `<child>: its work link could not be repointed to the retained worktree
4688
+ <movedTo> (<why>) and still points at <link>; repoint it by hand: ln -sfn
4689
+ …`, or `<child>: its attachment changed during the retire, so its work was
4690
+ left as it is now and not repointed to the retained worktree <movedTo>;
4691
+ inspect <home>/work`. A child of a tree the retire removed (a clean extra
4692
+ tree, or `work/` with `--discard-worktree`): `<child>: its work was
4693
+ <tree>, which this retire removed (<why>); its work link <home>/work now
4694
+ points at a path that is gone`. A child that was repointed has no string:
4695
+ the text summary's `child <name>` line says where its work now links. No
4696
+ key is new.
4697
+
4698
+ An attached instance the plan lists under `ambiguous` is not stopped and
4699
+ not repointed, and has a string for each tree that was moved or removed:
4700
+ the sentence above for a removed tree, followed by ` (it records this
4701
+ instance as its parent under a name that is not unique, so the retire did
4702
+ not stop it)`, or, for a re-homed tree, `<instance>: its work was <tree>,
4703
+ which this retire re-homed to <movedTo>; its work link <home>/work was not
4704
+ repointed and now points at a path that is gone (it records … did not stop
4705
+ it); to repoint it by hand: ln -sfn …`. A `--self` retirement's receipt
4706
+ does not carry these strings.
4651
4707
  - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
4652
4708
  notCopied?, afterHooks?}`, present when a recovery was written. One retire
4653
4709
  writes at most one recovery directory, and `path` is that directory.
@@ -4736,7 +4792,7 @@ nothing is established. A plain or
4736
4792
  always does (`[]` when there are none). One child still running after the
4737
4793
  grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
4738
4794
  `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
4739
- `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
4795
+ <a id="retire-children-running"></a>`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
4740
4796
  `code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
4741
4797
  only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
4742
4798
  (<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
package/docs/desktop.md CHANGED
@@ -353,10 +353,17 @@ join** says who else may join it. Both are read from the workspace's committed
353
353
  `souls:`; a team nobody may join yet says so. The address (the team on the
354
354
  messaging provider) and the members running in it follow.
355
355
 
356
- The **Setup** tab's List view starts with the workspace's **host**, the
357
- repository that holds `oats-workspace.yaml`, and marks every repository the
358
- workspace trusts for souls and capabilities as a **Member**. The host is a
359
- member too. A legend under the title explains both badges.
356
+ The **Setup** tab's List view is one column. Under the workspace's name, one
357
+ line counts its members (and those that need attention), its packages and the
358
+ state of the lock. The next line says where the workspace is declared. An
359
+ **Overview** says that the workspace's **host**, the repository that holds
360
+ `oats-workspace.yaml`, defines the workspace: its member repositories and its
361
+ packages. **For developers** (folded) explains how a repository becomes a
362
+ member and what each member state means. Then **Shared through Git** lists
363
+ what the workspace declares (Members, with the host first and tagged
364
+ **Host**, Packages and Defaults). **This computer** lists what is not shared:
365
+ this deployment's settings, lock, CLI and instances, the member clones, and
366
+ the machines that run the workspace.
360
367
 
361
368
  ## A workspace's machines
362
369
 
@@ -79,7 +79,7 @@ and the rules its tests pin.
79
79
  | `souls/` | this repository's own souls (a workspace member) |
80
80
  | `docs/` | the reference pages, schemas, design records and release notes |
81
81
  | `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
82
- | `scripts/` | the test runner (`run-tests.mjs`) and its reporter of unasserted warnings, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
82
+ | `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
83
83
  | `test/` | the kernel and CLI suites, with their fixtures |
84
84
 
85
85
  ## Kernel modules
@@ -443,7 +443,7 @@ scaling by call count.
443
443
 
444
444
  | command | what it checks |
445
445
  |---|---|
446
- | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output |
446
+ | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output, or a test file leaves something in its temporary directory |
447
447
  | `npm run test:session` | the suites that have followed a variable of the session that runs them, with every such variable set to a value that cannot work (`scripts/test-session-inheritance.mjs`) |
448
448
  | `npm run check` | syntax of every shipped file |
449
449
  | `npm run check:pi` | the pi adapter's TypeScript |
@@ -472,6 +472,65 @@ its own; a line a child wrote into a pipe the test reads is the test's, and
472
472
  does not count. `test/unasserted-warnings.test.mjs` pins the rule with nested
473
473
  runs.
474
474
 
475
+ **A test file leaves nothing behind.** Where a test makes a directory, it
476
+ registers the removal there (`t.after`, or a list the file empties when it has
477
+ ended), so a test that fails or times out removes it too; and a fixture is
478
+ ended, not only removed (`v2Deployment({ t })`, below). A file whose setup is
479
+ shared by its tests does that setup in a `test.before` hook, not at its top
480
+ level: a file that throws while it loads runs no hook, `test.after` included,
481
+ so a step that failed would leave what the steps before it made
482
+ (test/tui-acts.test.mjs). On a development host
483
+ the leftovers of runs that passed once used up the inodes of the temporary
484
+ file system, and every test that makes a directory then failed with "no
485
+ space", whatever the change under test (awebai/oats#1025). The root run holds
486
+ the rule:
487
+
488
+ - `scripts/run-tests.mjs` makes one directory for the run, and each test
489
+ file's process is preloaded with `scripts/test-file-tmpdir.mjs`, which gives
490
+ the file a directory of its own inside it: as `TMPDIR`, and as
491
+ `TMUX_TMPDIR`, which is tmux's default place. A tmux client that runs with
492
+ no `TMUX_TMPDIR` of a fixture makes its socket directory there, where the
493
+ run sees it, instead of reaching the host's default server. `TMUX` is not
494
+ changed: a client that names no server (no `-L` or `-S`) and inherits
495
+ `TMUX`, as in a run from a session inside tmux, still uses that session's
496
+ server and makes nothing the run sees. The run names its directory to the
497
+ preload in `OATS_TEST_RUN_DIR`, and the preload takes that variable out of
498
+ the file's environment before any code of the file runs. No test sees it,
499
+ nor any process a test starts.
500
+ - When the run has ended it reads each file's directory. If one is not empty
501
+ the run fails, even if every test passed, and names each file and what it
502
+ left.
503
+ - One name is not counted, by its exact name: `node-compile-cache`. Node makes
504
+ it under the temporary directory when a tool a test starts asks for a
505
+ compile cache (npm does), so under the root run it is made in the file's
506
+ own directory and goes with the run's. It is Node's, not something the file
507
+ left. A developer's shared cache, the one in the platform's temporary
508
+ directory, is neither used nor removed by a root run; a file run alone uses
509
+ it as before, and no test deletes it. The run's processes do not inherit
510
+ `NODE_COMPILE_CACHE` either: with a developer's set, no process of the run
511
+ writes into that cache.
512
+ - The run's directory is removed when the run has ended, whatever was left in
513
+ it. A run that is killed leaves that one directory: `ot-*` under the
514
+ temporary directory, or under `/tmp` when that path is longer than 20
515
+ characters.
516
+ - A file's directory, `<parent>/ot-XXXXXX/<n>`, takes from a socket's path
517
+ what `/tmp` alone did not. ssh binds a control socket at
518
+ `<OATS_HOME_DIR>/ssh/<40 hex>` plus a 17-byte suffix, in 104 bytes: 86 for
519
+ the path. A fixture whose `OATS_HOME_DIR` holds it keeps it short: a
520
+ 5-character prefix and `<base>/h` (`o-up-`) come to 85 bytes when the
521
+ run's parent resolves to at most 12 characters, as `/tmp` does on Linux
522
+ and on macOS (`/private/tmp`), with up to 999 files. Longer, the kernel
523
+ warns that the path is too long and runs ssh without connection reuse,
524
+ which fails the run as any unasserted warning does: run the suite with a
525
+ `TMPDIR` of `/tmp` then.
526
+ - The run sees what is made under the file's temporary directory: by the
527
+ file's process, by a process it starts with that environment, and by the
528
+ fixture helpers (`fixtureBase` and `privateTmuxTmpdir`, below), in a
529
+ process the test started with `inheritedEnv()` too. It does not see what a
530
+ process makes when a test built its environment without `TMPDIR`.
531
+
532
+ `test/left-behind.test.mjs` pins the rule with nested runs.
533
+
475
534
  Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
476
535
  load with only Desktop dependencies installed. The release builds Desktop that
477
536
  way: its `desktop-build` job installs and tests inside `packages/desktop` and
@@ -535,6 +594,31 @@ which fails with `ENOTEMPTY` (awebai/oats#451). So:
535
594
 
536
595
  Never paper over such a race with a retry around the cleanup.
537
596
 
597
+ A process that a test kills can leave such a writer too. Killing a process
598
+ that starts processes of its own ends that one alone: a child it had just
599
+ started goes on by itself and writes where it was told to after its parent has
600
+ gone, and it has not run a line yet, so it has announced itself nowhere. The
601
+ Desktop server's tests are the case: the server runs the CLI, and a fake CLI
602
+ writes its log in the test's directory. Such a test starts the process with
603
+ `startGroup` and closes it with `closeGroup`
604
+ (`test/helpers/process-group.mjs`):
605
+
606
+ - `startGroup` starts it as `spawn` does, as the leader of a process group of
607
+ its own, which holds whatever it starts.
608
+ - `closeGroup` kills that one process and waits until its group, that process
609
+ among it, is empty. The bound, 30 s, covers the whole close from its start:
610
+ a group that outlives it fails the test and names every process that is
611
+ left, the killed one too if it still runs. Only then does the test remove
612
+ what they worked in.
613
+ - A group of its own is not in the terminal's foreground group, so an
614
+ interrupt of the test's process does not reach it. The helper passes it on:
615
+ on `SIGINT`, `SIGTERM` or `SIGHUP` it kills every group that process
616
+ started, whole, and then the signal ends the process as it would have. A
617
+ test process killed with `SIGKILL` passes nothing on: what it started stays,
618
+ as any child of a process killed that way does.
619
+
620
+ `test/process-group.test.mjs` pins the three.
621
+
538
622
  A test never reaches the operator's tmux. The kernel creates sessions on the
539
623
  server named `oats` (`tmux -L oats`), which tmux resolves under `TMUX_TMPDIR`,
540
624
  and acts on every existing session through its recorded socket
@@ -624,7 +708,12 @@ inherits it (awebai/oats#816):
624
708
  - **A short base.** `fixtureBase(prefix)` makes the fixture directory under
625
709
  the platform's temporary directory, or under `/tmp` when that is longer than
626
710
  20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
627
- realpath, taken once.
711
+ realpath, taken once. Under the root run the temporary directory is the
712
+ test file's own (above), and is used whatever its length, so that nothing a
713
+ fixture makes is outside what the run reads; the run keeps it short. The
714
+ helper knows it by what the runner makes (`ot-XXXXXX/<n>`, with the file
715
+ `<n>.file` beside it) and by no variable, so a process a test starts with
716
+ `inheritedEnv()` uses it too.
628
717
  - **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
629
718
  name or branch segment) and `pathOfLength(base, n)` (an absolute path under
630
719
  the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
@@ -743,4 +832,10 @@ inherits it (awebai/oats#816):
743
832
  still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
744
833
  and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
745
834
  `t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
746
- built removes its base itself.
835
+ built removes its base itself. Removing the base is not ending the fixture:
836
+ only `fx.cleanup` stops the fixture's tmux server, checks for leftover
837
+ processes and removes the fixture's private `TMUX_TMPDIR`
838
+ (`privateTmuxTmpdir()`), which is made beside the base and never inside it.
839
+ So a fixture that was made and never ended leaves that directory, and the
840
+ root run fails on it (awebai/oats#1025). A file that collects its fixtures
841
+ ends each of them in the hook that used to remove their bases.
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.1.0
43
+ oats.okf: v5.2.0
44
44
  oats.aweb: v1.27.3
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
@@ -84,8 +84,10 @@ operations in full.
84
84
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
85
85
 
86
86
  - **`oats.okf`** consults the soul's external OKF bases, keeps instance
87
- knowledge, and briefs eligible working instances to propose durable claims
88
- at checkpoints by directly spawning `oats.okf/knowledge-harvester`. The
87
+ knowledge, and teaches the harvest duty in its IMPORTANT inject block and
88
+ compulsory `okf-propose` skill, not the task briefing. Eligible instances
89
+ propose durable claims at finished tasks or PR hand-overs by directly
90
+ spawning `oats.okf/knowledge-harvester`. The
89
91
  soul-only `knowledge: { harvest: off }` forbids harvest while retaining
90
92
  consultation. No host switch or automatic transcript/retire capture remains;
91
93
  `knowledge-maintainer` reviews the resulting Git PRs.
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.1.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.2.0** (OATS **>=0.49.0**). 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 |
@@ -14,6 +14,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
14
14
  | Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
15
15
  | `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
16
16
  | Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
17
+ | Instance home: `okf-harvest-policy.json` | Provider-written duty at spawn, exposed by `oats okf status`; not publication authority. |
17
18
  | Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
18
19
  | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
19
20
 
@@ -24,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
24
25
  ```yaml
25
26
  # oats-workspace.yaml (excerpt)
26
27
  packages:
27
- oats.okf: v5.1.0
28
+ oats.okf: v5.2.0
28
29
  defaults:
29
30
  knowledge: { oats.okf: { from: package } }
30
31
  stores:
@@ -49,10 +50,15 @@ settings:
49
50
 
50
51
  Upgrading from 4.x requires the ordered
51
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
52
- just editing a version line. For 5.1.0, upgrade to OATS >=0.49.0 before moving
53
- the provider pin: that kernel first supports the public source-event lookup
54
- after retirement. Re-spawn harvesters to receive the new capture hook and
55
- instructions; restarting a session keeps its copied provider.
53
+ just editing a version line. For 5.2.0, OATS >=0.49.0 remains required:
54
+ that kernel first supports the public source-event lookup after retirement.
55
+
56
+ **Upgrade:** pin `oats.okf: v5.2.0` and run `oats sync`. Only new spawns get
57
+ the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
+ homes keep their copied provider even after a session restart. Deployments
59
+ whose briefings never mentioned harvesting now get knowledge proposals at
60
+ eligible checkpoints; souls not ready for this must declare
61
+ `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
56
62
 
57
63
  ### Bindings document
58
64
 
@@ -142,9 +148,11 @@ soul's opt-out:
142
148
  knowledge: { harvest: off }
143
149
  ```
144
150
 
145
- That soul keeps consultation and working-memory guidance, receives no
146
- checkpoint-harvest directive, and its material is refused by the
147
- harvester's required spawn hook. Absence gives the normal proposal flow.
151
+ That soul keeps consultation and working-memory guidance but has no harvest
152
+ duty. The shared IMPORTANT block and compulsory skill pointer still ship,
153
+ with an explicit exception; the provider's spawn-recorded answer says `off`.
154
+ Independently, the harvester's required spawn hook refuses that soul's
155
+ material. Absence gives the normal proposal flow.
148
156
  A soul's `harvest: on` is not a replacement switch. Host cleanup never
149
157
  changes the soul declaration. `knowledge: none` removes the layer entirely.
150
158
 
@@ -152,36 +160,66 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
152
160
 
153
161
  ### The flow
154
162
 
155
- 1. **Consult.** Read accepted soul knowledge at task start, after compaction
156
- and before decisions; keep instance `STATE.md`, `log.md` and `notes/`.
157
- Working instances never write accepted knowledge themselves.
158
- 2. **Propose at checkpoints.** When work merits a checkpoint, update notes
159
- and write a self-contained proposal: what to save, why and the backing
160
- notes. It has exactly one line `Source: instance <name>, home <path>, soul
161
- <name>` naming the actual source. From the source home:
163
+ 1. **Consult and keep instance knowledge current.** Read accepted soul
164
+ knowledge at task start, after compaction and before decisions. Keep
165
+ `STATE.md`, `log.md` and `notes/` up to date as work happens. The
166
+ capability's **IMPORTANT** inject block makes this upkeep and eligible
167
+ checkpoint harvesting a duty; reading **okf-propose** is compulsory.
168
+ Neither duty depends on TASK.md. Run `oats okf status` from instance home
169
+ to learn the duty recorded at spawn: `on` means follow the skill, `off`
170
+ means no harvest, and `unknown` or an error means stop and report, never
171
+ infer permission or edit the record. Working instances never write
172
+ accepted knowledge themselves.
173
+ 2. **Propose only at a finished task or PR hand-over.** First update state,
174
+ log and relevant notes. Apply `knowledge-theory` and search accepted
175
+ knowledge (`oats okf search`, then `cat`): already accepted with nothing
176
+ to add means no proposal. Most checkpoints propose nothing. Make at most
177
+ **one proposal for that completed unit of work**; handing over its PR and
178
+ closing the same task are not two opportunities. Never launch per commit,
179
+ per decision, per review round or merely because a PR opened.
180
+
181
+ Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
182
+ home: What (one claim per concept), Why, Evidence (observations, dates,
183
+ limits and accepted concepts cited), and optional `## Backing notes` with
184
+ one `- notes/<file>.md` entry per note. It has exactly one line
185
+ `Source: instance <name>, home <path>, soul <name>` naming the actual
186
+ source, a pointer to verify rather than authority. Claim only for owned
187
+ nodes; a lesson for a node the soul only reads is named in one line in its
188
+ hand-back for that node's owner.
189
+
190
+ **Before spawning:** one harvester at a time per instance. Record its
191
+ returned name and proposal in log.md, and do not spawn another while
192
+ `oats status` still lists the last one. Check available memory immediately
193
+ before spawning: on Linux, `free -g` must show at least 8 GB available;
194
+ elsewhere use the host's documented check. If availability cannot be
195
+ established, is below the floor, or the host is under memory pressure,
196
+ defer. These are instructions, not a scheduler or a memory reservation.
197
+ Keep deferred proposals/notes and record the reason and waiting claims in
198
+ STATE.md, log.md and the hand-back. Reconsider at a natural task boundary,
199
+ never by polling, sleeping or stopping other instances to make room.
200
+
201
+ From instance home, preview and then apply the skill's command when the
202
+ gates permit it:
162
203
 
163
204
  ```sh
164
205
  oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
165
206
  ```
166
207
 
167
- Never combine `--relation unrelated` with `--relative-to`. There is no
208
+ Never combine `--relation unrelated` with `--relative-to`, or override
209
+ the kernel's harness/model selection. An unrelated harvester can outlive
210
+ its proposer; a child would tie their lifetimes together. There is no
168
211
  automatic transcript capture, source registry, worker cursor or retire
169
- harvest. An unrelated harvester can outlive its source. Proposers need
170
- not stay alive: the harvester can check their recorded retirement recovery.
171
- Keep backing evidence in the source home or that recovery until capture;
172
- never treat missing source authority as permission to invent it.
173
-
174
- One proposal per checkpoint, each concept a claim of its own in it, and
175
- claims only for the nodes the source soul owns; a lesson for a node it only
176
- reads goes in one line in the instance's hand-back, for that node's owner.
177
- One harvester at a time, per instance: the source notes the
178
- harvester's instance name and spawns no other while `oats status` still
179
- lists it, since a harvester retires once it has handed over. What it learns
180
- meanwhile goes into its next proposal; an instance that hands back with one
181
- still listed names it and the claims still waiting. A harvester retained
182
- after a publication failure stays listed, so it holds back its source's
183
- later proposals: once that failure is dealt with, the operator retires it
184
- (`oats retire <harvester>`).
212
+ harvest. Keep backing notes until the harvester retires; the proposer
213
+ itself need not stay alive. Its recorded retirement recovery can supply
214
+ evidence before capture, so do not dispose of it before capture.
215
+ Missing source authority never permits inventing it.
216
+
217
+ A refused or uncertain spawn is reported, not retried in a loop. If the
218
+ last harvester is still listed at hand-back, name it and the claims still
219
+ waiting; do not wait for it or spawn around it. A harvester retained after
220
+ a publication failure stays listed and holds back later proposals. Once
221
+ that failure is dealt with, the operator retires it (`oats retire
222
+ <harvester>`).
185
223
  3. **Capture, judge and submit.** Before the model starts, the required spawn
186
224
  hook checks the source's live record or the completed recovery named by
187
225
  its public retirement event. Source identity, single-incarnation history,
@@ -227,7 +265,7 @@ is historical 4.x context, not instructions for operating 5.0.
227
265
 
228
266
  Secrets, credentials, private paths and verbatim third-party messages are
229
267
  left out. So is personal data, in the same sentence at every place an agent
230
- is told what to leave out (the capturing instance, the proposal brief, the
268
+ is told what to leave out (the capturing instance, the proposing skill, the
231
269
  harvester when it edits and when it reads its diff, and the maintainer's
232
270
  review):
233
271
 
@@ -264,13 +302,14 @@ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest
264
302
 
265
303
  | Capability | Composed into | Skills |
266
304
  |---|---|---|
267
- | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
305
+ | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory` |
268
306
  | `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
269
307
  | `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
270
308
 
271
- Only the working soul's eligible **spawn brief** gives the proposal-spawn
272
- command. Shared consultation injects/skills also reach opted-out souls and
273
- do not unconditionally direct a harvest.
309
+ The capability's **IMPORTANT** inject block gives the duty and compulsory
310
+ pointer; **okf-propose** holds the procedure. These shared texts also reach
311
+ opted-out souls, with the explicit exception and provider status answer.
312
+ No source TASK brief contains harvest or proposal direction.
274
313
 
275
314
  ## Inspection and operator commands
276
315
 
@@ -304,6 +343,22 @@ are rooted in the base, never outside it. A failed fetch may serve cached
304
343
  accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
305
344
  and `index`. The consultation skill teaches navigation and citation.
306
345
 
346
+ ### Read the harvest duty
347
+
348
+ ```sh
349
+ oats okf status --json
350
+ ```
351
+
352
+ The provider's answer is `result.harvest: "on"` with `reason: "default"`, or
353
+ `"off"` with `reason: "soul-opt-out"`. It reads only home-local spawn state,
354
+ not the network, bases, TASK.md or a soul file. Missing state is `"unknown"`
355
+ with `reason: "spawn-state-missing"`; malformed or linked state refuses.
356
+ Neither unknown nor failure permits a proposal. Report it and respawn with
357
+ the current provider; never hand-create a policy or reinterpret later
358
+ settings as the spawn decision. `--home PATH` selects an explicit home.
359
+ This answer is instruction state, not publication authority: the harvester
360
+ still independently checks its recorded source's opt-out.
361
+
307
362
  ### Inspect
308
363
 
309
364
  ```sh
@@ -9,8 +9,8 @@ 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.10.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.10.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -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.1.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.2.0`); `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