@awebai/oats 0.49.0 → 0.50.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.
@@ -901,8 +901,8 @@ or the recorded window is gone and no pane on that server works in the home;
901
901
  and, always, no live process on this host works in the home (a harness
902
902
  started by hand elsewhere counts). Retire then runs its hooks and preserves
903
903
  its work as usual. If the recorded window is still there, a pane or a process
904
- works in the home (the refusal names its pid), or the process scan (`lsof`)
905
- cannot run, retire refuses with
904
+ works in the home (the refusal names its pid), or the
905
+ [process scan](#the-process-scan) cannot run, retire refuses with
906
906
  `E_RUNTIME_ENDPOINT_UNKNOWN`, even with `--force`: stop that session yourself,
907
907
  then retire again. `oats retire <instance> --plan` says which case applies.
908
908
 
@@ -912,11 +912,28 @@ home. When the recorded server cannot be reached because its socket file is
912
912
  missing (after a reboot), retire proceeds only when no process on this host
913
913
  works in the home (any process whose working directory is in the home, not
914
914
  only the harness); a tmux server that lost its socket file still runs, and
915
- recreates the socket when its process is sent `SIGUSR1`. That check needs
916
- `lsof`: on a host without it, a retire whose recorded socket file is missing
917
- is refused, and the message says that `lsof` is missing; install it, then
918
- retire. A scan that does not complete (a timeout, for example) refuses the
919
- same way, also for a home without its receipt.
915
+ recreates the socket when its process is sent `SIGUSR1`. A
916
+ [process scan](#the-process-scan) that cannot run or does not complete (a
917
+ timeout, for example) refuses the same way, also for a home without its
918
+ receipt. Status, start and stop apply the same rule to a missing socket file
919
+ ([Sessions](execution-targets.md#missing-socket)).
920
+
921
+ <a id="the-process-scan"></a>
922
+ **The process scan.** "No process works in the home" comes from one scan of
923
+ the host's processes and their working directories. On Linux it reads
924
+ `/proc` (each process's `cwd` link, `comm` and `stat`); elsewhere (macOS) it
925
+ runs `lsof`. A Linux host whose `/proc/self/cwd` cannot be read uses `lsof`
926
+ too. On a host with neither, `oats doctor` says so in a
927
+ `process-scan-unavailable` information line, and retire refuses where it must
928
+ rule out a live process (a home without its session receipt, a missing
929
+ recorded tmux socket, a Herdr home), as do session start and stop when a
930
+ recorded tmux socket is missing: install `lsof`. The scan sees only the
931
+ processes this user may inspect: a process of another user, or a
932
+ non-dumpable one of the same user (such as `ssh-agent`), is not seen by
933
+ either mechanism, so one of those working in the home does not stop a
934
+ retire. Refusing whenever such a process exists would refuse on every host
935
+ (root daemons, `ssh-agent`). The harness OATS launches runs as the user and
936
+ can be inspected, and it is the process the scan exists to find.
920
937
 
921
938
  `oats retire <instance> --self` lets an instance retire itself when the human
922
939
  or briefing says it is done. A live harness cannot give a stable final
@@ -1044,6 +1061,15 @@ leaves `work/` untouched. For each tree:
1044
1061
  the branch name with characters outside `A-Za-z0-9._-` replaced by `-`, or
1045
1062
  `detached-<12 hex>` when HEAD is detached. A target that exists gets `-2`,
1046
1063
  `-3`, and so on. A tree whose HEAD cannot be read is re-homed too.
1064
+ `work/` is re-homed under the same rule.
1065
+
1066
+ The leaf is one path component, so it is bounded: at most 231 bytes before
1067
+ its `-N` (NAME_MAX, 255, less a 16-byte margin and 8 bytes kept for `-N`;
1068
+ the leaf is ASCII, so bytes are characters). A leaf that fits is the
1069
+ flattened branch as it is. A longer one, from a long branch, is cut to 224
1070
+ bytes, its trailing `-` trimmed, and followed by `-` and the first 6 hex of
1071
+ the SHA-256 of the full branch name, so two branches that share a long
1072
+ prefix get different leaves. The plan's `movedTo` is the same name.
1047
1073
  - **A tree the retire cannot handle refuses it.** A locked tree (`git worktree
1048
1074
  lock`) refuses before anything runs: a retire that would remove the home
1049
1075
  finds the lock in its first inspection, before the session is stopped and
@@ -1082,6 +1108,42 @@ recovery are in no commit: a retained worktree or the source may still hold
1082
1108
  them, or the recovery may be the only copy, so inspect them before you
1083
1109
  remove it.
1084
1110
 
1111
+ `oats doctor` lists them all. It prints one `retained-recovery:` line per
1112
+ recovery copy in each instances directory of the deployment, and one
1113
+ `retained-worktree:` line per retained worktree. Each kind starts with a line
1114
+ that gives its total. At most 50 items follow, then `… and N more`. The lines
1115
+ are also in `oats doctor --json`, in `information[]`. They are read-only: doctor
1116
+ runs Git without helpers or optional locks, refreshes no index and follows no
1117
+ link. A fact doctor can't read is said on its line.
1118
+
1119
+ - A recovery line gives the path, the instance, `phase` and `classes` from
1120
+ `recovery.json`, the size, and whether `after-hooks/` is there. A recovery
1121
+ whose `recovery.json` is missing or unreadable is listed and says so, with
1122
+ the instance taken from the directory's name. A dot-named entry is the
1123
+ staging of a copy that a retire could not remove (`unfinished copy`).
1124
+ - A retained worktree line gives the path, the repository, the branch (or
1125
+ `detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
1126
+ (staged or unstaged changes, conflicts, untracked or ignored files, an
1127
+ operation in progress). Doctor doesn't ask Git for the status of a
1128
+ repository whose configuration names a content filter (`filter.<driver>.clean`
1129
+ or `.process`), because the status would run it: the line says `clean:
1130
+ unknown` and names the filter. The status never enters a submodule: it
1131
+ compares only the commit each one is at. A tree with a submodule is then
1132
+ `clean: unknown (submodule work trees not read)`, or `not clean` when the
1133
+ rest of it is, with `submodule work trees not read` after it. An entry that isn't a registered worktree is listed and
1134
+ says why.
1135
+ - Both end with the reachability fact for the HEAD commit. It is checked in the
1136
+ source repository against every ref but the tree's own branch:
1137
+ `commits: all reachable from <ref>`, `commits: <n> not reachable from any
1138
+ other ref`, `commits: HEAD <commit> is not in the source repository`, or
1139
+ `commits: unknown (<why>)`. For a recovery, the HEAD is that of its `repo/`
1140
+ clone, and the source repository is the one its copied home's
1141
+ `instance.json` records. That path is only a hint: it is used only when it
1142
+ is a Git repository's top level. A recovery with no `repo/` says `commits:
1143
+ no repository copy`. When a retained worktree of the same repository is on
1144
+ the recovery's branch, the recovery line names it: the uncommitted bytes
1145
+ may be in both.
1146
+
1085
1147
  **Recovery copies** are at
1086
1148
  `<instances>/.oats-retirement/recovery/<instance>-<random>/`, beside the
1087
1149
  homes of the agent the instance belonged to. The retire summary prints the
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.8.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.9.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.0.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -15,6 +15,10 @@
15
15
  * - Paths in the answers are POSIX and relative to the capability directory. `--file` reads only a path the
16
16
  * show lists (the inject, a listed skill file): no other file of the capability is readable through it.
17
17
  *
18
+ * - A manifest that declares `triggerSources` (#669) shows them exactly as declared, and the problems a trigger
19
+ * naming them would get (lib/trigger-sources.mjs) as `triggerSourceProblems`: a malformed declaration never
20
+ * refuses the show (containment), as it never refuses the capability.
21
+ *
18
22
  * Every text is untrusted repository content; a consumer renders it as plain text or through a sanitising
19
23
  * renderer (the docs say so).
20
24
  */
@@ -25,6 +29,7 @@ import { bindRemote } from "./packages.mjs";
25
29
  import { locatedContractWarnings } from "./capability-contract.mjs";
26
30
  import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
27
31
  import { memberRowByKey } from "./workspace.mjs";
32
+ import { triggerSourcesOf } from "./trigger-sources.mjs";
28
33
 
29
34
  export const CAPABILITY_SHOW_API = 1;
30
35
  /** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
@@ -169,6 +174,14 @@ const header = (source) => ({ capabilityShowApi: CAPABILITY_SHOW_API, name: sour
169
174
  /** What the capability declares and this kernel ignores (an unknown hook event), where its manifest is read. */
170
175
  const contractWarnings = (source) => locatedContractWarnings(source.manifest, source.kind === "package" ? `package:${source.package}:${source.dir}/oats.json` : `${source.repoKey}:${source.dir}/oats.json`);
171
176
 
177
+ /** The trigger sources a manifest declares, as declared, and their use-time problems: added keys, each only when
178
+ * there is something to say. */
179
+ function triggerSourceKeys(manifest) {
180
+ if (manifest?.triggerSources === undefined) return {};
181
+ const { problems } = triggerSourcesOf(manifest);
182
+ return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
183
+ }
184
+
172
185
  /** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
173
186
  export async function capabilityShow(source, { remote, remoteOptions }) {
174
187
  const r = bindRemote(remote, remoteOptions);
@@ -195,7 +208,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
195
208
  skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
196
209
  }
197
210
  }
198
- return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source) };
211
+ return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest) };
199
212
  }
200
213
 
201
214
  /** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.