@awebai/oats 0.61.0 → 0.63.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/README.md +1 -1
- package/bin/oats.mjs +27 -12
- package/docs/capabilities.md +1 -1
- package/docs/desktop-cli-api.md +30 -2
- package/docs/execution-targets.md +89 -4
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +13 -0
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/release-notes/v0.63.0.md +135 -0
- package/docs/souls-and-instances.md +6 -1
- package/docs/upgrading.md +135 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +73 -23
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/lib/tree-copy.mjs +188 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +200 -139
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +116 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1527 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +62 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +65 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +110 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +137 -17
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +116 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +136 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +241 -0
- package/packages/record/lib/capture-worker.mjs +74 -0
- package/packages/record/lib/derived-state.mjs +58 -17
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +121 -66
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +46 -14
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/skills/oats-getting-started/SKILL.md +1 -1
- package/docs/macos-test-runs.md +0 -246
package/README.md
CHANGED
|
@@ -231,7 +231,7 @@ This README explains the framework and its direction. Advanced mechanisms such a
|
|
|
231
231
|
|
|
232
232
|
## Contributing and releases
|
|
233
233
|
|
|
234
|
-
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS can be run on a
|
|
234
|
+
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see [named test runs](docs/named-test-runs.md).
|
|
235
235
|
|
|
236
236
|
Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the [release notes](docs/release-notes/) before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
|
|
237
237
|
|
package/bin/oats.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* oats — the OATS command line.
|
|
4
4
|
*
|
|
5
|
-
* oats doctor [dir] [--soul <s>] [--json] show
|
|
5
|
+
* oats doctor [dir] [--soul <s>] [--json] show deployment and offline capture warnings; --soul: composition only
|
|
6
6
|
* oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
|
|
7
7
|
* agents/), then sync
|
|
8
8
|
* oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
|
|
@@ -25,6 +25,7 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
|
+
import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
|
|
28
29
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
29
30
|
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
30
31
|
import {
|
|
@@ -104,7 +105,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
104
105
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
105
106
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
106
107
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
107
|
-
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", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size"];
|
|
108
|
+
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", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running"];
|
|
108
109
|
/** Commands `--server <id>` runs on a registered server. */
|
|
109
110
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
110
111
|
const flag = (name) => {
|
|
@@ -829,7 +830,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
829
830
|
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
830
831
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
831
832
|
...(problems.length ? { problems } : {}),
|
|
832
|
-
warnings: hookEvents.warnings,
|
|
833
|
+
warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
|
|
833
834
|
};
|
|
834
835
|
}
|
|
835
836
|
/** Kernel/bridge version skew (published in lockstep from one tag), in every pi folder a launch
|
|
@@ -876,6 +877,7 @@ async function doctor(dir) {
|
|
|
876
877
|
for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
877
878
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
878
879
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
880
|
+
if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
|
|
879
881
|
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
880
882
|
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
881
883
|
if (soulName) {
|
|
@@ -3463,7 +3465,13 @@ async function sessionCmd() {
|
|
|
3463
3465
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3464
3466
|
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3465
3467
|
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3466
|
-
|
|
3468
|
+
// What earlier attaches left (a viewer whose attach died without detaching): one line, on
|
|
3469
|
+
// stderr, before the client takes the terminal, and only when something was removed.
|
|
3470
|
+
const onSwept = ({ sessions, tables }) => {
|
|
3471
|
+
const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
|
|
3472
|
+
if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
|
|
3473
|
+
};
|
|
3474
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), onSwept });
|
|
3467
3475
|
return;
|
|
3468
3476
|
}
|
|
3469
3477
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -4070,12 +4078,12 @@ const EXPERIMENTAL_CMDS = new Set(["dress", "spawn", "segments", "mind"]);
|
|
|
4070
4078
|
async function recordCmd(sub) {
|
|
4071
4079
|
process.argv.splice(2, 1);
|
|
4072
4080
|
if (sub === "setup") {
|
|
4073
|
-
// setup writes a node into the user's Claude settings and into the capture
|
|
4081
|
+
// setup writes a node into the user's Claude settings and into the capture service's unit,
|
|
4074
4082
|
// and nothing rewrites them but setup run again: it is handed the rule's answer for the node
|
|
4075
4083
|
// running this kernel (docs/capabilities.md, "The node a hook writes down"). The script is
|
|
4076
4084
|
// imported into this process, so the variable is set here, over whatever the caller's
|
|
4077
4085
|
// environment held; packages/record imports nothing of the kernel.
|
|
4078
|
-
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture
|
|
4086
|
+
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture service stop when it goes away", remedy: "run `oats setup` again" });
|
|
4079
4087
|
if (warning) console.error(`oats: warning: ${warning}`);
|
|
4080
4088
|
process.env.OATS_NODE_BIN = node;
|
|
4081
4089
|
}
|
|
@@ -4885,8 +4893,8 @@ Usage:
|
|
|
4885
4893
|
[--launch-config <name>|none] command and preflight; read-only, nothing
|
|
4886
4894
|
[--harness r] [--model m] started; a named configuration is a unit, so
|
|
4887
4895
|
[--yolo | --no-yolo] --json a disagreeing --harness is refused
|
|
4888
|
-
oats doctor [dir] [--soul <name>] [--json] resolved targets
|
|
4889
|
-
--soul shows final composed AGENTS.md
|
|
4896
|
+
oats doctor [dir] [--soul <name>] [--json] resolved targets and offline capture warnings;
|
|
4897
|
+
--soul shows final composed AGENTS.md only
|
|
4890
4898
|
oats update [--check] [--yes] check npm for a newer kernel and move the pi bridge
|
|
4891
4899
|
[--dir <deployment>] in every pi folder the deployment's launches use
|
|
4892
4900
|
(docs/upgrading.md); then run oats doctor
|
|
@@ -4994,15 +5002,22 @@ Usage:
|
|
|
4994
5002
|
|
|
4995
5003
|
The turn record (core — every conversation captured, searchable, replicated):
|
|
4996
5004
|
oats capture [--watch|--status] land Claude Code/pi/codex sessions and aw
|
|
4997
|
-
[--owner <name>] [--root <dir>] client logs in the record
|
|
4998
|
-
|
|
5005
|
+
[--owner <name>] [--root <dir>] client logs in the record: one bounded
|
|
5006
|
+
supervised reconciliation pass; partial
|
|
5007
|
+
passes exit 0 with work pending
|
|
5008
|
+
oats capture --hook launch a detached pass; exit 0 means
|
|
5009
|
+
capture launched, not completed
|
|
5010
|
+
oats capture --health [--json] offline installation, run and issue
|
|
5011
|
+
diagnosis; captures nothing
|
|
4999
5012
|
oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]
|
|
5000
5013
|
one session file (an archived session),
|
|
5001
5014
|
captured as --home capture would
|
|
5002
5015
|
oats recall [--kind k] [--thread t] search the whole record — mail, chat,
|
|
5003
5016
|
[--from f] [--show id] <query> sessions — with exact turn provenance
|
|
5004
|
-
oats setup [--owner <name>] [--
|
|
5005
|
-
[--no-service] [--no-hooks]
|
|
5017
|
+
oats setup [--owner <name>] [--root <dir>] [--replace-service]
|
|
5018
|
+
[--no-service] [--no-hooks] [--dry-run]
|
|
5019
|
+
install hooks + periodic capture
|
|
5020
|
+
(launchd/systemd), then run the first pass
|
|
5006
5021
|
|
|
5007
5022
|
oats experimental <dress|spawn|segments|mind> EXPERIMENTAL tools over the record —
|
|
5008
5023
|
selection and agent synthesis; unproven by
|
package/docs/capabilities.md
CHANGED
|
@@ -842,7 +842,7 @@ A package that also runs under a kernel older than the variable falls back to
|
|
|
842
842
|
`oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
|
|
843
843
|
own process, over any value the caller's environment held, before it runs the
|
|
844
844
|
turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
845
|
-
into the capture hooks and the capture
|
|
845
|
+
into the capture hooks and the capture service's unit. In the third case
|
|
846
846
|
`oats setup` carries the warning, a dry run included.
|
|
847
847
|
|
|
848
848
|
### The worktree event
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -46,7 +46,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
48
|
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
|
|
49
|
-
"status-retire-state","session-inspect-size"],
|
|
49
|
+
"status-retire-state","session-inspect-size","session-inspect-running"],
|
|
50
50
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
51
51
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
52
52
|
"capabilityShowApi":1}
|
|
@@ -124,6 +124,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
124
124
|
| `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) |
|
|
125
125
|
| `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)) | |
|
|
126
126
|
| `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
127
|
+
| `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
127
128
|
| `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"}`) | |
|
|
128
129
|
| `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
|
|
129
130
|
| `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
|
|
@@ -5139,7 +5140,34 @@ answered before any effect and carries [`details.holder`](#busy-holder)). The
|
|
|
5139
5140
|
codes a retire answers only before any effect are
|
|
5140
5141
|
[one list](#before-effect-codes). A recovery whose Git status disagrees with
|
|
5141
5142
|
the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
|
|
5142
|
-
source, recovery}], total}}` (the first 10 paths).
|
|
5143
|
+
source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
|
|
5144
|
+
bytes disagree with the source's (`worktree recovery verification disagreed
|
|
5145
|
+
with the source`) carries `details: {home, recoveryDisagreement: {basis:
|
|
5146
|
+
"current", entries: [{path, kind}], complete, stoppedBy?}}`, and the message
|
|
5147
|
+
names its first 5 entries. The refusal itself is the exact digest comparison
|
|
5148
|
+
and is unchanged; this report is read only after it refused, from the source
|
|
5149
|
+
and the copy as they are then (`basis: "current"`), so a source that changed
|
|
5150
|
+
since its bytes were recorded can show other differences, or none. `kind` is
|
|
5151
|
+
one of `missing` (in the source, not the copy), `extra`, `type`, `mode`,
|
|
5152
|
+
`link-target` and `file-content`, nothing is listed below a `missing`,
|
|
5153
|
+
`extra` or `type` entry, and one path can carry several kinds. `path` is
|
|
5154
|
+
relative to the worktree, with the same Git paths left out as the
|
|
5155
|
+
comparison: each printable ASCII byte as itself, a backslash as `\\`, every
|
|
5156
|
+
other byte as `\xHH`. No content, link target or absolute path is reported,
|
|
5157
|
+
and an entry that is a link is compared as a link, never followed. Every
|
|
5158
|
+
read is by path, so what is read is checked against what was listed: a file
|
|
5159
|
+
must be the regular file it was listed as (opened without following a link
|
|
5160
|
+
or waiting on a FIFO), and a directory the one it was listed as, before and
|
|
5161
|
+
after its listing and when the search leaves it; otherwise the search stops
|
|
5162
|
+
as `unreadable` and nothing found below that directory is reported. A
|
|
5163
|
+
replacement that is undone before the replaced directory is checked again is
|
|
5164
|
+
not detected: what was read through it can then be compared and named. Every
|
|
5165
|
+
path named is relative to the worktree. The search is bounded: at most 20 entries,
|
|
5166
|
+
200,000 directory entries read (counted as each listing is read, so no
|
|
5167
|
+
listing goes past the budget), 64 MiB of file bytes read (files are compared
|
|
5168
|
+
in chunks, sizes first) and 5 seconds, checked between filesystem calls; when it stops early, `complete` is `false` and
|
|
5169
|
+
`stoppedBy` names why (`discrepancies`, `entries`, `bytes`, `time`, or
|
|
5170
|
+
`unreadable` when a tree could not be read). Usage errors are text on
|
|
5143
5171
|
stderr, not envelopes.
|
|
5144
5172
|
|
|
5145
5173
|
<a id="retire-reached"></a>
|
|
@@ -40,7 +40,9 @@ is the default); `tmux` must be installed on the execution host. A launched
|
|
|
40
40
|
home keeps the session it recorded: `session start` and `restart` never
|
|
41
41
|
re-read the defaults. The session target is recorded twice: in
|
|
42
42
|
`instance.json` and in an independent lifecycle receipt. Every session command
|
|
43
|
-
checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise
|
|
43
|
+
checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise, with
|
|
44
|
+
`details.fields` naming what differs; see [Inspect, input and
|
|
45
|
+
attach](#inspect-input-and-attach)).
|
|
44
46
|
|
|
45
47
|
### tmux
|
|
46
48
|
|
|
@@ -1064,6 +1066,43 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1064
1066
|
live claim that the instance needs input from a human, `{since, producer,
|
|
1065
1067
|
reason, message}`, or `null`; it is non-null only for a running harness
|
|
1066
1068
|
(docs/desktop-cli-api.md, "Waiting on you").
|
|
1069
|
+
With feature `session-inspect-running`, every successful result also
|
|
1070
|
+
carries `running`, a boolean read from the same pane observation by the
|
|
1071
|
+
same rule `oats status --json` uses for a row's `running`: `true` for a live
|
|
1072
|
+
non-shell process in the agent pane (`state: unknown`), a harness behind a
|
|
1073
|
+
wrapper shell included; `false` for a fallback shell (`state: shell`, where
|
|
1074
|
+
`present` stays `true`), an absent or dead pane or a missing home
|
|
1075
|
+
(`stopped`) and a home that never launched (`not-launched`). It costs no
|
|
1076
|
+
second observation: at most one process-table read, and only for a pane
|
|
1077
|
+
whose own command is a shell. `running` is activity at the authorized
|
|
1078
|
+
endpoint. It does not say the agent is generating, idle, healthy or ready
|
|
1079
|
+
for input, nor that it consumed a wake, and it does not prove which
|
|
1080
|
+
executable runs if a process inside the pane was replaced. When the
|
|
1081
|
+
backend or the process table cannot be read, or the pane answer is
|
|
1082
|
+
malformed or split, inspect is an error as before, never `running: false`.
|
|
1083
|
+
That includes a tmux server that is gone (`no server running on` its
|
|
1084
|
+
socket, as after a reboot): status reads that row as `running: false`, and
|
|
1085
|
+
inspect answers `E_SESSION_UNAVAILABLE`. Wherever inspect answers, its
|
|
1086
|
+
`running` is the one status reports.
|
|
1087
|
+
A consumer that sees no `running` (an older kernel or an older remote host)
|
|
1088
|
+
may read `state: unknown` on a successful result as running; a failed
|
|
1089
|
+
inspect is unknown, never stopped.
|
|
1090
|
+
`session inspect --server <id> --home <home> --json` relays the execution
|
|
1091
|
+
host's `running`, or its absence, as the host answered.
|
|
1092
|
+
A home whose `instance.json` disagrees with its session receipt is refused
|
|
1093
|
+
with `E_RUNTIME_AUTHORITY_MISMATCH` before any pane or process is read; the
|
|
1094
|
+
same refusal from any other session command, or in the answer of
|
|
1095
|
+
`oats retire`, carries the same details (the record a deferred
|
|
1096
|
+
`retire --self` leaves keeps only the code and message). Its `details.fields` names the differing fields, in this order, from this
|
|
1097
|
+
vocabulary only: `launched`, `tmux.session`, `tmux.window`, `tmux.socket`
|
|
1098
|
+
(the socket compared resolved, so a relative spelling of the same socket
|
|
1099
|
+
agrees). It carries no paths, values or receipt content. `launched` is
|
|
1100
|
+
listed unless a blocked or incomplete launch prompt explains
|
|
1101
|
+
`launched: false`; such a retained prompt is still allowed while its
|
|
1102
|
+
endpoint agrees, and only the endpoint fields that differ are named
|
|
1103
|
+
otherwise. A missing or invalid receipt stays `E_RUNTIME_ENDPOINT_UNKNOWN`
|
|
1104
|
+
and malformed metadata keeps its own refusal; neither carries
|
|
1105
|
+
`details.fields`.
|
|
1067
1106
|
- **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
|
|
1068
1107
|
NUL) as exactly one bracketed paste followed by exactly one Enter. The text
|
|
1069
1108
|
is never run by a shell. Existing endpoint authority, fallback-shell,
|
|
@@ -1103,6 +1142,50 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1103
1142
|
another session, another agent's terminal. Your own sessions keep your
|
|
1104
1143
|
setting.
|
|
1105
1144
|
|
|
1145
|
+
**An attach that dies without detaching leaves nothing behind.** A
|
|
1146
|
+
cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh can end
|
|
1147
|
+
`oats` and its tmux client together. `oats` itself then removes nothing, so
|
|
1148
|
+
the tmux server does. Once its client has attached, the viewer's client
|
|
1149
|
+
sets a `client-detached` hook on the viewer session alone: when a client
|
|
1150
|
+
leaves and none is left, the hook kills the viewer session. It is set after
|
|
1151
|
+
the attach, so a viewer whose client never attached is removed by `oats`
|
|
1152
|
+
or by the next attach's sweep. From then on, the server removes the viewer
|
|
1153
|
+
when its last client's connection drops without a word from the client:
|
|
1154
|
+
`oats` and its client SIGKILLed together (oomd, a stop timeout). A client
|
|
1155
|
+
that ends any other way (a hang-up, a termination, a `detach-client` from
|
|
1156
|
+
another client) is not seen by that hook: `oats` removes the viewer as it
|
|
1157
|
+
ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
|
|
1158
|
+
`destroy-unattached`: on tmux 3.4 it crashes the agents' server when another
|
|
1159
|
+
client detaches the viewer. A keyed viewer's key table (below)
|
|
1160
|
+
belongs to the server, not to the session, and its `client-detached` hook
|
|
1161
|
+
unbinds the table as it kills the session. For a viewer session that ends
|
|
1162
|
+
another way (its agent's window ends, a `kill-session`), a keyed viewer sets
|
|
1163
|
+
one global hook entry on the agents' server, `session-closed[900]`: when a
|
|
1164
|
+
session whose name is a viewer's closes, the entry unbinds the key table of
|
|
1165
|
+
that name. It is the only global hook entry OATS owns there.
|
|
1166
|
+
Every keyed viewer sets the same entry again, which leaves it unchanged,
|
|
1167
|
+
and no other index is touched. Keep your own `session-closed` hooks
|
|
1168
|
+
(`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
|
|
1169
|
+
900 is replaced. A global `client-detached` hook of yours does not run
|
|
1170
|
+
for a viewer's client whose connection dropped: the viewer session's own
|
|
1171
|
+
hook takes its place there. The entry needs `run-shell -C`, which tmux has from 3.2.
|
|
1172
|
+
Before 3.2 it does nothing, and the next attach's sweep removes the table.
|
|
1173
|
+
|
|
1174
|
+
Every attach also sweeps the server before it opens its viewer. It removes:
|
|
1175
|
+
|
|
1176
|
+
- a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
|
|
1177
|
+
whose attaching process, the pid in its name, no longer exists;
|
|
1178
|
+
- a viewer key table whose session no longer exists.
|
|
1179
|
+
|
|
1180
|
+
The sweep keeps a viewer whose attach is alive, even with no client: its
|
|
1181
|
+
client may not have attached yet. It also never removes an attached
|
|
1182
|
+
viewer, anything not named as a viewer, or the `oatsview-locked` table
|
|
1183
|
+
that every viewer without a key shares. When it removed something, the
|
|
1184
|
+
attach prints one line on stderr before the viewer opens:
|
|
1185
|
+
`oats: removed <n> leftover viewer session(s) and <m> key table(s) of
|
|
1186
|
+
earlier attaches`. A failed sweep is not the attach's failure; the next
|
|
1187
|
+
attach sweeps again.
|
|
1188
|
+
|
|
1106
1189
|
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1107
1190
|
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
|
1108
1191
|
DEC mode 2026, so a terminal that receives a redraw in two pieces does not
|
|
@@ -1119,9 +1202,11 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1119
1202
|
The key is taken from the agent's input: the agent never receives it while
|
|
1120
1203
|
this viewer is attached. A keyed viewer reads a tmux key table of its own,
|
|
1121
1204
|
named as its temporary session and removed with it, so the key is bound
|
|
1122
|
-
for that viewer alone.
|
|
1123
|
-
|
|
1124
|
-
|
|
1205
|
+
for that viewer alone. The key's binding also removes the viewer session's
|
|
1206
|
+
`client-detached` hook before it detaches: the session outlives its client
|
|
1207
|
+
until `oats` has read that the key was used, and `oats` then removes it.
|
|
1208
|
+
Check the feature in `oats version --json` before passing the flag: a
|
|
1209
|
+
kernel without it ignores the flag and opens a viewer with no exit.
|
|
1125
1210
|
|
|
1126
1211
|
The key is one of these, spelled exactly (case-sensitive):
|
|
1127
1212
|
|
package/docs/implementation.md
CHANGED
|
@@ -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`), 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
|
|
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, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
|
|
83
83
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
84
84
|
|
|
85
85
|
## Kernel modules
|
|
@@ -96,6 +96,7 @@ and the rules its tests pin.
|
|
|
96
96
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
97
97
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
98
98
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
99
|
+
| `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
|
|
99
100
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
100
101
|
| `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
|
|
101
102
|
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|