@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.
Files changed (90) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +27 -12
  3. package/docs/capabilities.md +1 -1
  4. package/docs/desktop-cli-api.md +30 -2
  5. package/docs/execution-targets.md +89 -4
  6. package/docs/implementation.md +2 -1
  7. package/docs/named-test-runs.md +382 -0
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-lane.md +13 -0
  11. package/docs/release-notes/v0.62.0.md +223 -0
  12. package/docs/release-notes/v0.63.0.md +135 -0
  13. package/docs/souls-and-instances.md +6 -1
  14. package/docs/upgrading.md +135 -11
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +73 -23
  17. package/lib/doctor-capture.mjs +35 -0
  18. package/lib/session-viewer.mjs +86 -7
  19. package/lib/tree-copy.mjs +188 -7
  20. package/package-catalog.json +1 -1
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/record/README.md +87 -13
  24. package/packages/record/bin/capture-hook.mjs +8 -0
  25. package/packages/record/bin/capture.mjs +200 -139
  26. package/packages/record/bin/recall.mjs +8 -3
  27. package/packages/record/bin/setup.mjs +116 -225
  28. package/packages/record/bin/turn-record.mjs +2 -2
  29. package/packages/record/docs/capture-service.md +1527 -28
  30. package/packages/record/docs/capture-status.schema.json +429 -12
  31. package/packages/record/lib/capture-admission.mjs +82 -0
  32. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  33. package/packages/record/lib/capture-aw.mjs +31 -12
  34. package/packages/record/lib/capture-budget.mjs +31 -0
  35. package/packages/record/lib/capture-cc.mjs +39 -6
  36. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  37. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  38. package/packages/record/lib/capture-command-operation.mjs +37 -0
  39. package/packages/record/lib/capture-command-output.mjs +62 -0
  40. package/packages/record/lib/capture-command-worker.mjs +6 -0
  41. package/packages/record/lib/capture-command.mjs +65 -0
  42. package/packages/record/lib/capture-completion.mjs +152 -0
  43. package/packages/record/lib/capture-context.mjs +50 -0
  44. package/packages/record/lib/capture-default-roots.mjs +30 -0
  45. package/packages/record/lib/capture-discovery.mjs +114 -0
  46. package/packages/record/lib/capture-failures.mjs +45 -0
  47. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  48. package/packages/record/lib/capture-health-installation.mjs +117 -0
  49. package/packages/record/lib/capture-health.mjs +116 -0
  50. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  51. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  52. package/packages/record/lib/capture-hook.mjs +26 -0
  53. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  54. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  55. package/packages/record/lib/capture-index-reset.mjs +110 -0
  56. package/packages/record/lib/capture-index-work.mjs +77 -0
  57. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  58. package/packages/record/lib/capture-issues.mjs +15 -2
  59. package/packages/record/lib/capture-lock.mjs +137 -17
  60. package/packages/record/lib/capture-native-unit.mjs +322 -0
  61. package/packages/record/lib/capture-pass.mjs +116 -0
  62. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  63. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  64. package/packages/record/lib/capture-retry.mjs +102 -0
  65. package/packages/record/lib/capture-run.mjs +125 -0
  66. package/packages/record/lib/capture-scratch.mjs +12 -3
  67. package/packages/record/lib/capture-service-definition.mjs +104 -0
  68. package/packages/record/lib/capture-service-install.mjs +362 -0
  69. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  70. package/packages/record/lib/capture-service-runner.mjs +18 -0
  71. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  72. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  73. package/packages/record/lib/capture-source-queue.mjs +199 -0
  74. package/packages/record/lib/capture-source-work.mjs +85 -0
  75. package/packages/record/lib/capture-state.mjs +16 -71
  76. package/packages/record/lib/capture-status.mjs +171 -0
  77. package/packages/record/lib/capture-supervisor.mjs +136 -0
  78. package/packages/record/lib/capture-watch.mjs +32 -0
  79. package/packages/record/lib/capture-work-session.mjs +241 -0
  80. package/packages/record/lib/capture-worker.mjs +74 -0
  81. package/packages/record/lib/derived-state.mjs +58 -17
  82. package/packages/record/lib/file-lines.mjs +22 -6
  83. package/packages/record/lib/formats.mjs +4 -3
  84. package/packages/record/lib/index-capture.mjs +97 -0
  85. package/packages/record/lib/index-db.mjs +121 -66
  86. package/packages/record/lib/index-reset.mjs +19 -0
  87. package/packages/record/lib/store.mjs +46 -14
  88. package/packages/record/lib/transcript-prefix.mjs +125 -0
  89. package/skills/oats-getting-started/SKILL.md +1 -1
  90. 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 macOS runner by hand: see [macOS test runs](docs/macos-test-runs.md).
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 the deployment; --soul: the instructions an instance of <s> would carry
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
- process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
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 watcher's unit,
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 watcher stop when it goes away", remedy: "run `oats setup` again" });
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, trust, requirements;
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; reconciliation
4998
- is the capture
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>] [--dry-run] install capture hooks + background watcher
5005
- [--no-service] [--no-hooks] (launchd/systemd), then run the first pass
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
@@ -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 watcher's unit. In the third case
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
@@ -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). Usage errors are text on
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. Check the feature in `oats version --json` before
1123
- passing the flag: a kernel without it ignores the flag and opens a viewer
1124
- with no exit.
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
 
@@ -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 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, 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 |