@awebai/oats 0.50.0 → 0.52.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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +43 -7
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
@@ -3,32 +3,86 @@
3
3
  * installed unless `oats schedule host install` is run explicitly, and
4
4
  * status reports what the OS says is loaded, never what a file implies. */
5
5
  import { execFileSync } from "node:child_process";
6
- import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
6
+ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
7
7
  import { homedir, platform, userInfo } from "node:os";
8
- import { dirname, join } from "node:path";
8
+ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
9
9
  import { fileURLToPath } from "node:url";
10
10
  import { hostScheduleDir, scheduleError } from "./schedule.mjs";
11
11
 
12
12
  export const LAUNCHD_LABEL = "ai.oats.schedule-tick";
13
13
  export const SYSTEMD_UNIT = "oats-schedule-tick";
14
14
  const OATS_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "oats.mjs");
15
+ /** The usual prefixes every unit PATH ends with, whether or not this host has them. */
16
+ const FALLBACK_PATH = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
17
+ /** A versioned Homebrew keg: <prefix>/Cellar/<formula>/<version>/…, gone at the next upgrade. */
18
+ const KEG = /^(.*)\/Cellar\/([^/]+)\/([^/]+)\//;
19
+ const REINSTALL = "run `oats schedule host install` again from the operator's shell (not from an instance home)";
15
20
 
16
21
  function escapeXml(s) { return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); }
22
+ function unescapeXml(s) { return String(s).replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&"); }
23
+
24
+ /** The installer's PATH entries a unit may carry. Dropped: entries inside an
25
+ * OATS instance home (an instance's `.oats/bin`, anything under
26
+ * `instanceHome`), entries inside a versioned Homebrew keg, and relative or
27
+ * empty entries. An entry missing today is kept: it may exist when the tick
28
+ * runs, and status reports it while it does not. */
29
+ export function unitPathEntries(envPath, { instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
30
+ const home = instanceHome && isAbsolute(instanceHome) ? resolve(instanceHome) : null;
31
+ const hazard = (entry) => {
32
+ if (!entry || !isAbsolute(entry)) return true;
33
+ const segments = entry.split(sep);
34
+ if (segments.some((s, i) => s === ".oats" && segments[i + 1] === "bin")) return true;
35
+ if (home && (resolve(entry) === home || resolve(entry).startsWith(home + sep))) return true;
36
+ return KEG.test(entry.endsWith("/") ? entry : `${entry}/`);
37
+ };
38
+ return String(envPath || "").split(":").filter((entry) => !hazard(entry));
39
+ }
40
+
41
+ function realpathOrNull(p) { try { return realpathSync(p); } catch { return null; } }
42
+ /** The node a unit runs: one that survives a Homebrew upgrade. A keg's
43
+ * `<prefix>/opt/<formula>/bin/node` when it is this node, else the first
44
+ * `node` on the filtered PATH that is this node, else `execPath` with a
45
+ * warning that the path is not stable. */
46
+ export function stableNode({ execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
47
+ const real = realpathOrNull(execPath);
48
+ const keg = real && KEG.exec(real);
49
+ if (keg) {
50
+ const opt = join(keg[1], "opt", keg[2], "bin", "node");
51
+ if (realpathOrNull(opt) === real) return { node: opt };
52
+ }
53
+ for (const entry of unitPathEntries(envPath, { instanceHome })) {
54
+ const candidate = join(entry, "node");
55
+ if (real && realpathOrNull(candidate) === real) return { node: candidate };
56
+ }
57
+ return { node: execPath, warning: `the node path ${execPath} is not stable (no Homebrew opt link and no node on PATH resolves to it): the timer stops when it goes away; install a node with a stable path and run \`oats schedule host install\` again` };
58
+ }
17
59
 
18
60
  /** launchd and systemd start units with a short PATH that has no Homebrew
19
61
  * tmux and no installed harness. The unit therefore carries an explicit
20
- * PATH: the installer's own PATH (the operator's tool environment) plus
21
- * the node running the installer and the usual prefixes. */
22
- export function hostPath({ node = process.execPath, envPath = process.env.PATH || "" } = {}) {
62
+ * PATH: the dir of the node it runs, the installer's own PATH (the
63
+ * operator's tool environment) without its hazards (unitPathEntries), and the
64
+ * usual prefixes. */
65
+ export function hostPath({ node = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
23
66
  const seen = new Set();
24
67
  const out = [];
25
- for (const p of [dirname(node), ...envPath.split(":"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]) {
68
+ for (const p of [dirname(node), ...unitPathEntries(envPath, { instanceHome }), ...FALLBACK_PATH]) {
26
69
  if (p && !seen.has(p)) { seen.add(p); out.push(p); }
27
70
  }
28
71
  return out.join(":");
29
72
  }
73
+ /** What `install` renders from the installer's environment: the stable node,
74
+ * the unit PATH, and the warnings the install answer carries. */
75
+ export function hostUnitPlan({ execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
76
+ const { node, warning } = stableNode({ execPath, envPath, instanceHome });
77
+ return { node, path: hostPath({ node, envPath, instanceHome }), warnings: warning ? [warning] : [] };
78
+ }
30
79
 
31
- export function renderLaunchdPlist({ node = process.execPath, oatsBin = OATS_BIN, logDir = join(hostScheduleDir(), "log"), intervalSec = 60, oatsHomeDir = process.env.OATS_HOME_DIR, path = hostPath({ node }) } = {}) {
80
+ /** An empty StartCalendarInterval dict fires at second 0 of every minute.
81
+ * ProcessType Standard: a Background job's start is throttled, and under
82
+ * load its node started long after the fire, past its minute. */
83
+ export function renderLaunchdPlist({ node, oatsBin = OATS_BIN, logDir = join(hostScheduleDir(), "log"), oatsHomeDir = process.env.OATS_HOME_DIR, path } = {}) {
84
+ if (node === undefined) node = hostUnitPlan().node;
85
+ if (path === undefined) path = hostPath({ node });
32
86
  const env = `\n <key>EnvironmentVariables</key>\n <dict>\n <key>PATH</key><string>${escapeXml(path)}</string>${oatsHomeDir ? `\n <key>OATS_HOME_DIR</key><string>${escapeXml(oatsHomeDir)}</string>` : ""}\n </dict>`;
33
87
  return `<?xml version="1.0" encoding="UTF-8"?>
34
88
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -44,9 +98,9 @@ export function renderLaunchdPlist({ node = process.execPath, oatsBin = OATS_BIN
44
98
  <string>--host</string>
45
99
  <string>--json</string>
46
100
  </array>
47
- <key>StartInterval</key><integer>${intervalSec}</integer>
101
+ <key>StartCalendarInterval</key><dict/>
48
102
  <key>RunAtLoad</key><false/>
49
- <key>ProcessType</key><string>Background</string>
103
+ <key>ProcessType</key><string>Standard</string>
50
104
  <key>StandardOutPath</key><string>${escapeXml(join(logDir, "tick.log"))}</string>
51
105
  <key>StandardErrorPath</key><string>${escapeXml(join(logDir, "tick.err"))}</string>${env}
52
106
  </dict>
@@ -58,14 +112,71 @@ export function renderLaunchdPlist({ node = process.execPath, oatsBin = OATS_BIN
58
112
  export function systemdQuote(value) {
59
113
  return `"${String(value).replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
60
114
  }
61
- export function renderSystemdUnits({ node = process.execPath, oatsBin = OATS_BIN, intervalSec = 60, oatsHomeDir = process.env.OATS_HOME_DIR, path = hostPath({ node }) } = {}) {
115
+ /** A calendar timer at second 0 of every minute; a minute missed while the
116
+ * machine was off or asleep is not run at wake (Persistent=false). */
117
+ export function renderSystemdUnits({ node, oatsBin = OATS_BIN, oatsHomeDir = process.env.OATS_HOME_DIR, path } = {}) {
118
+ if (node === undefined) node = hostUnitPlan().node;
119
+ if (path === undefined) path = hostPath({ node });
62
120
  const env = `Environment=${systemdQuote(`PATH=${path}`)}\n${oatsHomeDir ? `Environment=${systemdQuote(`OATS_HOME_DIR=${oatsHomeDir}`)}\n` : ""}`;
63
121
  return {
64
122
  service: `[Unit]\nDescription=OATS schedule tick\n\n[Service]\nType=oneshot\n${env}ExecStart=${systemdQuote(node)} ${systemdQuote(oatsBin)} schedule tick --host --json\n`,
65
- timer: `[Unit]\nDescription=OATS schedule tick every ${intervalSec}s\n\n[Timer]\nOnBootSec=${intervalSec}\nOnUnitActiveSec=${intervalSec}\nAccuracySec=5\nUnit=${SYSTEMD_UNIT}.service\n\n[Install]\nWantedBy=timers.target\n`,
123
+ timer: `[Unit]\nDescription=OATS schedule tick\n\n[Timer]\nOnCalendar=*-*-* *:*:00\nAccuracySec=1s\nPersistent=false\nUnit=${SYSTEMD_UNIT}.service\n\n[Install]\nWantedBy=timers.target\n`,
66
124
  };
67
125
  }
68
126
 
127
+ function systemdUnquote(quoted) {
128
+ return quoted.slice(1, -1).replace(/\\(.)/g, "$1").replace(/%%/g, "%");
129
+ }
130
+ const SYSTEMD_QUOTED = String.raw`"(?:[^"\\]|\\.)*"`;
131
+ /** The values an installed unit records, read from the file alone (never the
132
+ * caller's environment); null when the file is not in the shape oats renders. */
133
+ function recordedUnit(p) {
134
+ if (p.kind === "launchd") {
135
+ const text = readFileSync(p.plist, "utf8");
136
+ const value = (key) => { const m = new RegExp(`<key>${key}</key><string>([^<]*)</string>`).exec(text); return m ? unescapeXml(m[1]) : undefined; };
137
+ const args = /<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>/.exec(text);
138
+ const out = value("StandardOutPath");
139
+ const legacy = /<key>StartInterval<\/key>/.test(text);
140
+ if (!args || value("PATH") === undefined || out === undefined) return { legacy, unit: null };
141
+ // An absent OATS_HOME_DIR is "" (rendered as none), never the caller's.
142
+ const unit = { node: unescapeXml(args[1]), oatsBin: unescapeXml(args[2]), path: value("PATH"), oatsHomeDir: value("OATS_HOME_DIR") ?? "", logDir: dirname(out) };
143
+ return { legacy, unit, same: renderLaunchdPlist(unit) === text };
144
+ }
145
+ const service = readFileSync(p.service, "utf8"), timer = readFileSync(p.timer, "utf8");
146
+ const legacy = /^(OnBootSec|OnUnitActiveSec)=/m.test(timer);
147
+ const exec = new RegExp(`^ExecStart=(${SYSTEMD_QUOTED}) (${SYSTEMD_QUOTED}) `, "m").exec(service);
148
+ const env = (name) => { const m = new RegExp(`^Environment=("${name}=(?:[^"\\\\]|\\\\.)*")$`, "m").exec(service); return m ? systemdUnquote(m[1]).slice(name.length + 1) : undefined; };
149
+ if (!exec || env("PATH") === undefined) return { legacy, unit: null };
150
+ const unit = { node: systemdUnquote(exec[1]), oatsBin: systemdUnquote(exec[2]), path: env("PATH"), oatsHomeDir: env("OATS_HOME_DIR") ?? "" };
151
+ const rendered = renderSystemdUnits(unit);
152
+ return { legacy, unit, same: rendered.service === service && rendered.timer === timer };
153
+ }
154
+
155
+ /** What would stop or mislead the installed timer, as warnings: a recorded
156
+ * node or oats that is gone, a PATH entry that is gone (the fallback
157
+ * prefixes are not checked: not every host has them), and a unit that is
158
+ * not what this kernel renders from those same recorded values. */
159
+ function unitProblems(p) {
160
+ let read;
161
+ try { read = recordedUnit(p); } catch (e) { return [{ code: "unit-outdated", message: `the unit cannot be read: ${e.message}`, fix: REINSTALL }]; }
162
+ const problems = [];
163
+ const { unit } = read;
164
+ if (unit) {
165
+ const nodeMissing = !existsSync(unit.node);
166
+ if (nodeMissing) problems.push({ code: "node-missing", message: `the unit runs node at ${unit.node}, which does not exist`, fix: REINSTALL });
167
+ if (!existsSync(unit.oatsBin)) problems.push({ code: "oats-bin-missing", message: `the unit runs oats at ${unit.oatsBin}, which does not exist`, fix: REINSTALL });
168
+ for (const entry of unit.path.split(":")) {
169
+ // A gone node's own directory is node-missing's cause, not a PATH entry to remove.
170
+ if (nodeMissing && entry === dirname(unit.node)) continue;
171
+ if (entry && !FALLBACK_PATH.includes(entry) && !existsSync(entry)) problems.push({ code: "path-entry-missing", message: `the unit's PATH entry ${entry} does not exist`, fix: `restore ${entry}, or remove it from the operator's PATH and ${REINSTALL}` });
172
+ }
173
+ }
174
+ if (read.legacy) problems.push({ code: "unit-outdated", message: "the unit runs the tick on an interval, not at second 0 of every minute", fix: REINSTALL });
175
+ else if (!unit) problems.push({ code: "unit-outdated", message: "the unit is not in the shape oats renders", fix: REINSTALL });
176
+ else if (!read.same) problems.push({ code: "unit-outdated", message: "the unit differs from what this oats renders for it", fix: REINSTALL });
177
+ return problems;
178
+ }
179
+
69
180
  /** `unitDir` overrides the OS location (tests never touch a live timer's files). */
70
181
  export function hostUnitPaths(os = platform(), { unitDir } = {}) {
71
182
  if (os === "darwin") return { kind: "launchd", plist: join(unitDir || join(homedir(), "Library", "LaunchAgents"), `${LAUNCHD_LABEL}.plist`) };
@@ -78,46 +189,67 @@ function run(exec, argv) {
78
189
  catch (e) { return { ok: false, out: String(e.stdout || ""), err: String(e.stderr || e.message || "").trim() }; }
79
190
  }
80
191
 
81
- /** installed = the unit file exists; active = the OS reports it loaded/active. */
192
+ /** installed = the unit file exists; active = the OS reports it loaded/active;
193
+ * problems = unitProblems, warnings that never change installed or active. */
82
194
  export function hostUnitStatus({ exec, os = platform(), unitDir } = {}) {
83
195
  const p = hostUnitPaths(os, { unitDir });
84
196
  if (p.kind === "launchd") {
85
197
  const installed = existsSync(p.plist);
86
198
  const r = run(exec, ["launchctl", "print", `gui/${userInfo().uid}/${LAUNCHD_LABEL}`]);
87
- return { kind: p.kind, unit: p.plist, installed, active: r.ok };
199
+ return { kind: p.kind, unit: p.plist, installed, active: r.ok, problems: installed ? unitProblems(p) : [] };
88
200
  }
89
201
  if (p.kind === "systemd") {
90
202
  const installed = existsSync(p.timer) && existsSync(p.service);
91
203
  const r = run(exec, ["systemctl", "--user", "is-active", `${SYSTEMD_UNIT}.timer`]);
92
- return { kind: p.kind, unit: p.timer, installed, active: r.ok && r.out.trim() === "active" };
204
+ return { kind: p.kind, unit: p.timer, installed, active: r.ok && r.out.trim() === "active", problems: installed ? unitProblems(p) : [] };
205
+ }
206
+ return { kind: "unsupported", installed: false, active: false, problems: [] };
207
+ }
208
+
209
+ /** The unit files install writes for `os`, rendered from the installer's
210
+ * environment (hostUnitPlan): { kind, files: { <path>: <content> }, warnings }.
211
+ * Renders only: nothing is written and the OS is not asked. */
212
+ export function hostUnitFiles({ os = platform(), unitDir, execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME, oatsBin = OATS_BIN } = {}) {
213
+ const p = hostUnitPaths(os, { unitDir });
214
+ const { node, path, warnings } = hostUnitPlan({ execPath, envPath, instanceHome });
215
+ // The unit runs the oats that ran install: one inside an instance home goes away when that instance retires.
216
+ // The home's work counts as resolved too: an attached instance's work is a link into its owner's home.
217
+ if (instanceHome && isAbsolute(instanceHome)) {
218
+ const bin = realpathOrNull(oatsBin) ?? resolve(oatsBin);
219
+ const homes = [realpathOrNull(instanceHome) ?? resolve(instanceHome), realpathOrNull(join(instanceHome, "work"))].filter(Boolean);
220
+ if (homes.some((home) => bin === home || bin.startsWith(home + sep))) warnings.push(`the unit would run ${oatsBin}, inside the instance home ${instanceHome}: the timer stops when that instance retires; run \`oats schedule host install\` with the operator's installed oats, from the operator's own shell`);
93
221
  }
94
- return { kind: "unsupported", installed: false, active: false };
222
+ if (p.kind === "launchd") return { kind: p.kind, files: { [p.plist]: renderLaunchdPlist({ node, path, oatsBin }) }, warnings };
223
+ if (p.kind === "systemd") { const units = renderSystemdUnits({ node, path, oatsBin }); return { kind: p.kind, files: { [p.service]: units.service, [p.timer]: units.timer }, warnings }; }
224
+ throw scheduleError("E_SCHEDULE_HOST", `no host timer support on ${os}`);
95
225
  }
96
226
 
97
- export function installHostUnit({ exec, os = platform(), intervalSec = 60, unitDir } = {}) {
227
+ /** Writes hostUnitFiles and loads them; the answer is the status plus their warnings. */
228
+ export function installHostUnit({ exec, os = platform(), unitDir, execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
98
229
  const p = hostUnitPaths(os, { unitDir });
230
+ const { files, warnings } = hostUnitFiles({ os, unitDir, execPath, envPath, instanceHome });
99
231
  mkdirSync(join(hostScheduleDir(), "log"), { recursive: true });
100
232
  if (p.kind === "launchd") {
101
233
  mkdirSync(dirname(p.plist), { recursive: true });
102
234
  const status = hostUnitStatus({ exec, os, unitDir });
103
- const rendered = renderLaunchdPlist({ intervalSec });
235
+ const rendered = files[p.plist];
104
236
  // Idempotent: registering another scope while the same timer is active
105
237
  // must not unload an in-flight tick just to rewrite identical bytes.
106
- if (status.active && existsSync(p.plist) && readFileSync(p.plist, "utf8") === rendered) return status;
238
+ if (status.active && existsSync(p.plist) && readFileSync(p.plist, "utf8") === rendered) return { ...status, warnings };
107
239
  if (status.active) { const r = run(exec, ["launchctl", "bootout", `gui/${userInfo().uid}/${LAUNCHD_LABEL}`]); if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `launchctl bootout failed before reinstall: ${r.err}`); }
108
240
  writeFileSync(p.plist, rendered);
109
241
  const r = run(exec, ["launchctl", "bootstrap", `gui/${userInfo().uid}`, p.plist]);
110
242
  if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `launchctl bootstrap failed: ${r.err}`);
111
- return hostUnitStatus({ exec, os, unitDir });
243
+ return { ...hostUnitStatus({ exec, os, unitDir }), warnings };
112
244
  }
113
245
  if (p.kind === "systemd") {
114
246
  mkdirSync(dirname(p.timer), { recursive: true });
115
- const units = renderSystemdUnits({ intervalSec });
247
+ const units = { service: files[p.service], timer: files[p.timer] };
116
248
  const status = hostUnitStatus({ exec, os, unitDir });
117
- if (status.active && existsSync(p.service) && existsSync(p.timer) && readFileSync(p.service, "utf8") === units.service && readFileSync(p.timer, "utf8") === units.timer) return status;
249
+ if (status.active && existsSync(p.service) && existsSync(p.timer) && readFileSync(p.service, "utf8") === units.service && readFileSync(p.timer, "utf8") === units.timer) return { ...status, warnings };
118
250
  writeFileSync(p.service, units.service); writeFileSync(p.timer, units.timer);
119
251
  for (const argv of [["systemctl", "--user", "daemon-reload"], ["systemctl", "--user", "enable", "--now", `${SYSTEMD_UNIT}.timer`]]) { const r = run(exec, argv); if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `${argv.join(" ")} failed: ${r.err}`); }
120
- return hostUnitStatus({ exec, os, unitDir });
252
+ return { ...hostUnitStatus({ exec, os, unitDir }), warnings };
121
253
  }
122
254
  throw scheduleError("E_SCHEDULE_HOST", `no host timer support on ${os}`);
123
255
  }
package/lib/schedule.mjs CHANGED
@@ -35,7 +35,7 @@ import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
35
35
  import { pollSourced, tickTriggers } from "./triggers.mjs";
36
36
  import { resolveMemberClone } from "./instance-resolution.mjs";
37
37
  import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
38
- import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
38
+ import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
39
39
 
40
40
  export const SCHEDULE_FILE = "oats-schedules.json";
41
41
  export const SCHEDULE_API = 2;
@@ -493,7 +493,9 @@ export function launchOrderKey(js) { return String(js?.lastLaunchedAt || ""); }
493
493
  /** What a run's instance looks like now. Home gone = ended; a home that is
494
494
  * retiring is still there (its harness may be alive pending teardown) and
495
495
  * keeps its slot; present but no running harness = stopped (needs
496
- * attention, never removed); running = active; not inspectable = unknown. */
496
+ * attention, never removed), and so is one whose recorded tmux server is
497
+ * gone (sessionServerGone: after a reboot or a crash); running = active;
498
+ * not inspectable = unknown. */
497
499
  export function observeHome(home, io) {
498
500
  if (!home) return { outcome: "launched" };
499
501
  if (!existsSync(home)) return { outcome: "ended" };
@@ -507,7 +509,11 @@ export function observeHome(home, io) {
507
509
  // (or with no start receipt at all) is a shell a finished harness.
508
510
  if (s.present && s.state === "shell" && startupInProgress(home)) return { outcome: "starting" };
509
511
  return { outcome: "stopped" };
510
- } catch (e) { return { outcome: "unknown", error: e.message }; }
512
+ } catch (e) {
513
+ const lost = sessionServerGone(home, e.cause);
514
+ if (lost.gone) return { outcome: "stopped", note: "its tmux server is gone" };
515
+ return { outcome: "unknown", error: lost.why ? `cannot inspect session: ${lost.why}` : e.message };
516
+ }
511
517
  }
512
518
  function startupInProgress(home) {
513
519
  const pendingPath = join(home, ".oats-start-pending.json");
@@ -610,12 +616,23 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
610
616
  throw scheduleError(e.code || "E_SPAWN_FAILED", retained ? `${e.message} (home retained; effects unconfirmed)` : String(e.message || "spawn failed"), { details: e.details });
611
617
  }
612
618
  const res = envelope.result || {};
613
- return { instance: res.instance, home: res.home, launched: res.launched, materialized: "workspace" };
619
+ return { instance: res.instance, home: res.home, launched: res.launched, materialized: "workspace", ...runWarnings(res) };
614
620
  }
615
621
  /** Launch one spawn job. `io.spawn(root, agent, opts)` overrides the whole
616
622
  * launcher for tests. Otherwise the kernel's own `oats spawn` runs in the
617
623
  * deployment (workspace materialization: `.oats/modules`, module skills and
618
624
  * injects). */
625
+ /** A launch answer's warnings, for the run's record (feature schedule-run-warnings): present only when
626
+ * there are some. */
627
+ export function runWarnings(answer) {
628
+ const w = Array.isArray(answer?.warnings) ? answer.warnings.filter((x) => typeof x === "string") : [];
629
+ return w.length ? { warnings: w } : {};
630
+ }
631
+ /** A record updated in place by a later run keeps no earlier run's warnings. */
632
+ function withoutWarnings(record) {
633
+ const { warnings: _w, ...rest } = record || {}; void _w;
634
+ return rest;
635
+ }
619
636
  function launchSpawn(ws, def, minute, io) {
620
637
  const { root, agent, discover } = resolveScheduledAgent(ws, def);
621
638
  const purpose = `${def.purpose || def.id}-${purposeSuffix(minute)}`;
@@ -623,7 +640,7 @@ function launchSpawn(ws, def, minute, io) {
623
640
  let r;
624
641
  if (io?.spawn) r = io.spawn(root, agent, opts);
625
642
  else r = spawnViaCli(ws, root, agent, opts, workspaceSpawnContext(ws), io);
626
- const run = { instance: r.instance, home: r.home, launched: !!r.instance, kind: "spawn", ...(r.materialized ? { materialized: r.materialized } : {}) };
643
+ const run = { instance: r.instance, home: r.home, launched: !!r.instance, kind: "spawn", ...(r.materialized ? { materialized: r.materialized } : {}), ...runWarnings(r) };
627
644
  if (def.wake && r.home) {
628
645
  try { run.wakeSchedule = saveWakeForHome(ws, { instance: r.instance, home: r.home, wake: def.wake }); }
629
646
  catch (e) { run.wakeScheduleError = { code: e.code || "E_SCHEDULE_INVALID", message: e.message }; }
@@ -732,7 +749,7 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
732
749
  if (reserve && !reserve()) return { kind: "wake", action: "skipped", reason: "the job's slot is held by another process; delivery pending", pending: true };
733
750
  try {
734
751
  const r = (io?.start || startInstanceSession)(def.home);
735
- return { kind: "wake", action: "started", instance: r.instance, target: r.target, home: def.home, incarnation: incarnationOfHome(def.home), reason: "session was stopped; the message is pending until the session is active", pending: true, startedHarness: true };
752
+ return { kind: "wake", action: "started", instance: r.instance, target: r.target, home: def.home, incarnation: incarnationOfHome(def.home), reason: "session was stopped; the message is pending until the session is active", pending: true, startedHarness: true, ...runWarnings(r) };
736
753
  } catch (e) {
737
754
  return { kind: "wake", action: "skipped", reason: `start did not complete (${e.code || "error"}): ${e.message}; the slot is kept until the session is observed stopped or absent`, error: e.message, errorCode: e.code, pending: true, startedHarness: "unconfirmed" };
738
755
  }
@@ -753,7 +770,8 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
753
770
  * while its started harness is active, starting, unknown or retiring and
754
771
  * released when that harness is proven stopped (the start receipt's exit
755
772
  * marker) or its home is gone: a persistent home outliving its process
756
- * does not keep a slot. */
773
+ * does not keep a slot. Returns a spawn job's observed outcome, as it is
774
+ * recorded (a dry run records nothing), when its previous run is tracked. */
757
775
  function observePrevious(ws, id, def, js, io, now, { mutate }) {
758
776
  // An invalid definition (a stored captured one included) is reported on its
759
777
  // job by the tick and never observed.
@@ -766,7 +784,8 @@ function observePrevious(ws, id, def, js, io, now, { mutate }) {
766
784
  const tracked = def.kind === "wake" ? !!lock : !!home && ["launched", "active", "starting", "stopped", "unknown"].includes(lr?.outcome);
767
785
  if (!tracked || !home) return;
768
786
  const seen = observeHome(home, io);
769
- if (!mutate) return;
787
+ const outcome = seen.outcome === "starting" ? "active" : seen.outcome;
788
+ if (!mutate) return def.kind === "wake" ? undefined : outcome;
770
789
  if (def.kind === "wake") {
771
790
  if (seen.outcome === "ended" || seen.outcome === "stopped") {
772
791
  releaseJobLock(ws, id);
@@ -775,8 +794,19 @@ function observePrevious(ws, id, def, js, io, now, { mutate }) {
775
794
  }
776
795
  return;
777
796
  }
778
- js.lastRun = { ...lr, outcome: seen.outcome === "starting" ? "active" : seen.outcome, ...(seen.error ? { error: seen.error } : {}), ...(seen.outcome === "ended" ? { endedAt: now.toISOString() } : {}) };
797
+ // An observation's error and note replace the previous observation's.
798
+ const { error: _error, note: _note, ...run } = lr;
799
+ js.lastRun = { ...run, outcome, ...(seen.error ? { error: seen.error } : {}), ...(seen.note ? { note: seen.note } : {}), ...(seen.outcome === "ended" ? { endedAt: now.toISOString() } : {}) };
779
800
  if (seen.outcome === "ended") releaseJobLock(ws, id);
801
+ return outcome;
802
+ }
803
+ /** Why a due spawn job whose slot is held is skipped: the instance it
804
+ * launched (`outcome`, as observed) stopped, which needs a person, or it
805
+ * still runs. */
806
+ function heldSlotReason(js, outcome) {
807
+ if (outcome !== "stopped") return "still running";
808
+ const { instance, home } = js.lastRun;
809
+ return `previous instance stopped: retire it (oats retire ${shellWord(instance || basename(home))}) or start it again (oats session start --home ${shellWord(home)})`;
780
810
  }
781
811
 
782
812
  /** Evaluate every enabled job of `ws` for the current minute (or, with
@@ -784,8 +814,10 @@ function observePrevious(ws, id, def, js, io, now, { mutate }) {
784
814
  * reads only: no lock, state or definition is touched. Due jobs are
785
815
  * visited least-recently-launched first so one job cannot monopolize the
786
816
  * slot. An invalid definition is recorded on that job and the rest continue. */
787
- export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun = false, only, observeOnly = false, candidates, ctx = null } = {}) {
788
- const minute = minuteStart(now);
817
+ /** `firedAt` is when the timer fired this tick (the process start, before any
818
+ * work): the minute evaluated. `now` is the clock for every timestamp. */
819
+ export function tickWorkspace(ws, { now = new Date(), firedAt = now, io, reg, wsList, dryRun = false, only, observeOnly = false, candidates, ctx = null } = {}) {
820
+ const minute = minuteStart(firedAt);
789
821
  const key = minuteKey(minute);
790
822
  const registry = reg || readRegistry();
791
823
  const bound = scheduleCap(registry);
@@ -816,7 +848,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
816
848
  if (shape) { cronError = shape; due = false; }
817
849
  else { try { due = only ? true : dueAt(def, minute); } catch (e) { cronError = e.message; due = false; } }
818
850
  const errorCode = herdr ? { errorCode: herdr.code } : {};
819
- if (cronError) { if (!dryRun) js.lastRun = { ...(js.lastRun || {}), outcome: "invalid", error: `definition cannot be evaluated: ${cronError}`, ...errorCode }; record(id, "invalid", { error: cronError, ...errorCode }); continue; }
851
+ if (cronError) { if (!dryRun) js.lastRun = { ...withoutWarnings(js.lastRun), outcome: "invalid", error: `definition cannot be evaluated: ${cronError}`, ...errorCode }; record(id, "invalid", { error: cronError, ...errorCode }); continue; }
820
852
  if (def.kind === "wake" && js.pendingWake && def.enabled && !dryRun && !only) {
821
853
  const dueNow = due && js.lastAttemptedMinute !== key;
822
854
  const held = !!jobLockInfo(ws, id);
@@ -824,7 +856,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
824
856
  const run = performWake(def, io, { startIfStopped: dueNow, canStart, reserve: () => held || acquireJobLock(ws, id, { scheduledFor: js.pendingWake.scheduledFor, wake: true, home: def.home }) });
825
857
  if (run.startedHarness) js.lastLaunchedAt = now.toISOString();
826
858
  if (!existsSync(def.home)) releaseJobLock(ws, id);
827
- js.lastRun = { ...(js.lastRun || {}), ...run, outcome: run.action, completedPending: run.action === "delivered", pendingSince: js.pendingWake.scheduledFor, startedAt: js.lastRun?.startedAt || now.toISOString() };
859
+ js.lastRun = { ...withoutWarnings(js.lastRun), ...run, outcome: run.action, completedPending: run.action === "delivered", pendingSince: js.pendingWake.scheduledFor, startedAt: js.lastRun?.startedAt || now.toISOString() };
828
860
  if (!run.pending) delete js.pendingWake;
829
861
  if (dueNow) js.lastAttemptedMinute = key;
830
862
  record(id, run.action, { ...(run.reason ? { reason: run.reason } : {}), pending: !!run.pending });
@@ -834,7 +866,8 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
834
866
  if (js.lastAttemptedMinute === key && !only) continue;
835
867
  if (!due) continue;
836
868
  if (dryRun) {
837
- const reason = js.attempt ? "an earlier launch has no recorded result; run oats schedule reconcile" : jobLockInfo(ws, id) && def.kind !== "wake" ? "still running" : liveLocks(wsAll) >= bound && def.kind !== "wake" ? "host busy" : undefined;
869
+ // A dry run recorded no observation: the held slot's instance is observed here.
870
+ const reason = js.attempt ? "an earlier launch has no recorded result; run oats schedule reconcile" : jobLockInfo(ws, id) && def.kind !== "wake" ? heldSlotReason(js, observePrevious(ws, id, def, js, io, now, { mutate: false })) : liveLocks(wsAll) >= bound && def.kind !== "wake" ? "host busy" : undefined;
838
871
  record(id, reason ? "skipped" : "due", reason ? { reason } : {});
839
872
  continue;
840
873
  }
@@ -862,7 +895,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
862
895
  record(id, run.action, { ...(run.reason ? { reason: run.reason } : {}), pending: !!run.pending });
863
896
  continue;
864
897
  }
865
- if (jobLockInfo(ws, id)) { record(id, "skipped", { reason: "still running" }); continue; }
898
+ if (jobLockInfo(ws, id)) { record(id, "skipped", { reason: heldSlotReason(js, js.lastRun?.outcome) }); continue; }
866
899
  if (liveLocks(wsAll) >= bound) { record(id, "skipped", { reason: "host busy" }); continue; }
867
900
  // Persist the attempt before even reserving the launch slot. A crash in
868
901
  // the following gap leaves an inspectable unresolved attempt, never an
@@ -914,8 +947,15 @@ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, ca
914
947
  const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
915
948
  return Object.assign(ctx, { ws, local });
916
949
  }
917
- /** The host tick: every registered scope under the host lock. */
918
- export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
950
+ /** A stored minute key as a time, or null when it is not one. */
951
+ function minuteTime(key) {
952
+ const t = typeof key === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(key) ? Date.parse(`${key}:00Z`) : NaN;
953
+ return Number.isFinite(t) ? t : null;
954
+ }
955
+ /** The host tick: every registered scope under the host lock. It evaluates the
956
+ * minute it was fired for (`firedAt`, see tickWorkspace). */
957
+ export function tickHost({ now = new Date(), firedAt = now, io, dryRun = false } = {}) {
958
+ const minute = minuteStart(firedAt);
919
959
  const reg = readRegistry();
920
960
  const wsList = reg.workspaces.filter((w) => existsSync(w));
921
961
  // When this tick started: no trigger source's poll may end later than 50 s after it; `sourced`
@@ -936,14 +976,14 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
936
976
  for (const ws of wsList) {
937
977
  const ctx = contexts.get(ws);
938
978
  try {
939
- considered.push(...tickWorkspace(ws, { now, io, reg, wsList, dryRun, observeOnly: true, ctx }));
979
+ considered.push(...tickWorkspace(ws, { now, firedAt, io, reg, wsList, dryRun, observeOnly: true, ctx }));
940
980
  const defs = effectiveDefinitions(ws, ctx), st = readState(ws);
941
981
  for (const [id, def] of Object.entries(defs.jobs)) if (def?.kind !== "trigger") jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
942
982
  } catch (e) { considered.push({ workspace: ws, action: "error", error: e.message }); }
943
983
  }
944
984
  jobs.sort((a, b) => a.key.localeCompare(b.key) || a.ws.localeCompare(b.ws) || a.id.localeCompare(b.id));
945
985
  for (const j of jobs) {
946
- try { considered.push(...tickWorkspace(j.ws, { now, io, reg, wsList, dryRun, candidates: [j.id], ctx: contexts.get(j.ws) })); }
986
+ try { considered.push(...tickWorkspace(j.ws, { now, firedAt, io, reg, wsList, dryRun, candidates: [j.id], ctx: contexts.get(j.ws) })); }
947
987
  catch (e) { considered.push({ workspace: j.ws, id: j.id, action: "error", error: e.message }); }
948
988
  }
949
989
  // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
@@ -954,8 +994,14 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
954
994
  // Capability sources: every scope's in one most-overdue-first order, under the tick's one deadline.
955
995
  try { considered.push(...pollSourced(tick.sourced, { now, io, dryRun, reg, wsList, tickStart: tick.start, reserved: tick.reserved ?? 0 })); }
956
996
  catch (e) { considered.push({ action: "error", error: `trigger sources: ${e.message}` }); }
957
- if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
958
- return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
997
+ // The host's minute only moves forward: a slow tick that finishes after the
998
+ // next minute's tick leaves the later minute.
999
+ if (!dryRun) {
1000
+ const host = readHostState();
1001
+ const stored = minuteTime(host.minute);
1002
+ writeHostState({ ...host, lastTick: now.toISOString(), minute: stored !== null && stored > minute.getTime() ? host.minute : minuteKey(minute) });
1003
+ }
1004
+ return { tickedAt: now.toISOString(), minute: minuteKey(minute), considered, scheduler: schedulerStatus(undefined, io) };
959
1005
  };
960
1006
  return dryRun ? body() : withHostLock(body);
961
1007
  }
@@ -976,7 +1022,10 @@ export function runNow(ws, qid, { now = new Date(), io, force = false, ctx = nul
976
1022
  observePrevious(ws, id, def, js, io, now, { mutate: true });
977
1023
  writeState(ws, st);
978
1024
  if (js.attempt) throw scheduleError("E_SCHEDULE_UNRESOLVED", `schedule ${id} has a launch attempt without a recorded result; run oats schedule reconcile ${id} first`);
979
- if (def.kind !== "wake" && jobLockInfo(ws, id)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is still running`);
1025
+ if (def.kind !== "wake" && jobLockInfo(ws, id)) {
1026
+ const reason = heldSlotReason(js, js.lastRun?.outcome);
1027
+ throw scheduleError("E_SCHEDULE_RUNNING", reason === "still running" ? `schedule ${id} is still running` : `schedule ${id}: ${reason}`);
1028
+ }
980
1029
  if (def.kind !== "wake" && liveLocks(wsList) >= scheduleCap(reg)) throw scheduleError("E_SCHEDULER_BUSY", `host concurrency ${scheduleCap(reg)} reached`);
981
1030
  const considered = tickWorkspace(ws, { now, io, reg, wsList, only: id, ctx });
982
1031
  const after = readState(ws);
@@ -1026,7 +1075,7 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
1026
1075
  delete js.attempt;
1027
1076
  if (adopted) {
1028
1077
  const seen = observeHome(adopted.home, io);
1029
- js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: attemptKind, launched: true, ...adopted, outcome: seen.outcome, ...(seen.error ? { error: seen.error } : {}) };
1078
+ js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: attemptKind, launched: true, ...adopted, outcome: seen.outcome, ...(seen.error ? { error: seen.error } : {}), ...(seen.note ? { note: seen.note } : {}) };
1030
1079
  if (seen.outcome !== "ended") { if (!jobLockInfo(ws, id)) acquireJobLock(ws, id, { scheduledFor: attempt.scheduledFor, reconciled: true }); } else releaseJobLock(ws, id);
1031
1080
  } else {
1032
1081
  js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: attemptKind, launched: false, outcome: "launch-failed", error: clear ? "cleared by the operator after checking by hand" : "no instance found in the scope's roster for the unrecorded attempt" };
@@ -1393,5 +1442,5 @@ export function schedulerStatus(ws, io) {
1393
1442
  const host = readHostState();
1394
1443
  let unit = { installed: false, active: false };
1395
1444
  try { unit = (io?.hostStatus || (() => ({ installed: false, active: false, unavailable: true })))(); } catch (e) { unit = { installed: false, active: false, error: e.message }; }
1396
- return { installed: !!unit.installed, active: !!unit.active, ...(unit.unit ? { unit: unit.unit } : {}), ...(unit.error ? { error: unit.error } : {}), lastTick: host.lastTick || null, maxConcurrent: scheduleCap(reg), triggersMaxConcurrent: reg.triggersMaxConcurrent ?? null, tickIntervalSec: reg.tickIntervalSec, ...(ws ? { workspace: resolve(ws), registered: reg.workspaces.includes(resolve(ws)) } : {}), workspaces: reg.workspaces, live: liveLocks(reg.workspaces.filter((w) => existsSync(w))) };
1445
+ return { installed: !!unit.installed, active: !!unit.active, ...(unit.unit ? { unit: unit.unit } : {}), ...(unit.error ? { error: unit.error } : {}), problems: Array.isArray(unit.problems) ? unit.problems : [], lastTick: host.lastTick || null, maxConcurrent: scheduleCap(reg), triggersMaxConcurrent: reg.triggersMaxConcurrent ?? null, tickIntervalSec: reg.tickIntervalSec, ...(ws ? { workspace: resolve(ws), registered: reg.workspaces.includes(resolve(ws)) } : {}), workspaces: reg.workspaces, live: liveLocks(reg.workspaces.filter((w) => existsSync(w))) };
1397
1446
  }
package/lib/servers.mjs CHANGED
@@ -26,6 +26,7 @@ import { noteRuntimeName } from "./deprecation.mjs";
26
26
  import { readWaitingClaim } from "./instance-events.mjs";
27
27
  import { withDirLock } from "./dir-lock.mjs";
28
28
  import { shellWord } from "./core.mjs";
29
+ import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
29
30
 
30
31
  const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
31
32
  export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -921,8 +922,10 @@ export function resolveRoute(serverId, { instance, home } = {}, what = "session"
921
922
  if (home && !snap) snap = listSnapshots(serverId).find((s) => s.home && resolve(s.home) === resolve(home));
922
923
  if (instance && snap && snap.instance !== instance) throw serverError("E_HOME_MISMATCH", `--home ${home} is the saved route of ${snap.instance} on ${serverId}, not of ${instance}`);
923
924
  if (instance && !snap && home && basename(home) !== instance) throw serverError("E_HOME_MISMATCH", `--home ${home} is not the home of instance ${instance}`);
924
- const remoteHome = home || snap?.home || (instance ? instanceOnHost(serverId, instance, io).home : undefined);
925
925
  const target = snap?.target || targetOf(io.server || getServer(serverId));
926
+ // `io.beforeRoster(target)`: what a caller must establish about the host before this route asks
927
+ // it anything (a keyed attach's feature gate). It runs only when the roster is about to be read.
928
+ const remoteHome = home || snap?.home || (instance ? (io.beforeRoster?.(target), instanceOnHost(serverId, instance, io).home) : undefined);
926
929
  if (!remoteHome || !String(remoteHome).startsWith("/")) throw serverError("E_BAD_ARGS", `${what} --server needs --instance <name> or --home </absolute/remote/home>`);
927
930
  return { target, home: remoteHome, snapshot: snap };
928
931
  }
@@ -1162,11 +1165,24 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
1162
1165
  return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId } } : envelope, stderr, target };
1163
1166
  }
1164
1167
 
1165
- export function attachArgv(serverId, { instance, home } = {}, io = {}) {
1168
+ export function attachArgv(serverId, { instance, home, detachKey } = {}, io = {}) {
1166
1169
  io = { ...io, serverId };
1167
- const { target, home: remoteHome } = resolveRoute(serverId, { instance, home }, "session attach", io);
1170
+ const keyed = detachKey !== undefined;
1171
+ // A detach key is checked before anything is asked of the host.
1172
+ if (keyed) requireDetachKey(detachKey);
1173
+ // A kernel without the feature ignores the flag and opens a viewer no key leaves. So with a key
1174
+ // the probe always runs, under `skipVersionCheck` (--print) too: a printed argv is run as it is.
1175
+ // A host without the feature is sent the probe and nothing else: the gate comes before a name
1176
+ // is resolved through the host's roster, and before the `session` check, whose hint reads the
1177
+ // roster too. The probe is asked once (checkRemote keeps it).
1178
+ const requireDetachKeyRemote = (target) => {
1179
+ const remote = checkRemote(target, io);
1180
+ if (!remote.features.includes(DETACH_KEY_FEATURE)) throw Object.assign(serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise ${DETACH_KEY_FEATURE}; upgrade it there, or attach without --detach-key; nothing was sent`), { details: { feature: DETACH_KEY_FEATURE } });
1181
+ };
1182
+ const { target, home: remoteHome } = resolveRoute(serverId, { instance, home }, "session attach", keyed ? { ...io, beforeRoster: requireDetachKeyRemote } : io);
1183
+ if (keyed) requireDetachKeyRemote(target);
1168
1184
  if (!io.skipVersionCheck) requireSessionRemote(target, io, remoteHome);
1169
- const [bin, ...rest] = sshArgv(target, ["session", "attach", "--home", remoteHome], { control: controlUsable(target, io) });
1185
+ const [bin, ...rest] = sshArgv(target, ["session", "attach", "--home", remoteHome, ...(detachKey !== undefined ? ["--detach-key", detachKey] : [])], { control: controlUsable(target, io) });
1170
1186
  // -t: allocate a PTY; placed before `--` with the other ssh options.
1171
1187
  return { argv: [bin, "-t", ...rest], target, home: remoteHome };
1172
1188
  }