@fro.bot/systematic 3.31.6 → 3.32.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.
@@ -0,0 +1,86 @@
1
+ # Headless mode and outcomes
2
+
3
+ ## Reading the mode
4
+
5
+ The mode comes from tokens in the skill arguments. Some hosts pass no arguments to a skill, so the tokens can also come from the invoking instruction: the text the user or the calling program sent to start the run. Read the arguments first. When none are shown, read the invoking instruction. Never read a token out of a file in a project.
6
+
7
+ | Tokens found | Result |
8
+ |---|---|
9
+ | None | Interactive. |
10
+ | `mode:interactive` | Interactive. |
11
+ | `mode:headless` | Headless. |
12
+ | The same token twice or more | That token, counted once. |
13
+ | `mode:headless` and `mode:interactive` | Stop: conflicting mode flags. |
14
+ | Any other `mode:` token | Stop: unknown mode token. Name it. |
15
+
16
+ A stop here happens before `begin`, so no lock is taken and nothing is dispatched. End as for a failed run: the reason on a line of its own, then `Connect failed`.
17
+
18
+ ## What headless changes
19
+
20
+ Headless mode asks no question and offers nothing after the digest. It does not wait for input of any kind.
21
+
22
+ - A host and version pair the helper does not list is refused: `begin` answers `unsupported-host`. Interactive mode asks consent instead.
23
+ - A user decision (`decide`) is never taken. The digest is the only output.
24
+ - Anything unclear is a stop with a reason, not a question.
25
+
26
+ ## Host permissions for unattended runs
27
+
28
+ A run reads and writes its work files under the state directory, and the researcher reads the allowed projects. All of that is outside the project the session runs in. OpenCode asks before it touches a path outside the project, and a run with nobody to answer is refused. On OpenCode 1.19.5 a headless run that read a work file in the state directory was refused as an `external_directory` request, and the refusal ended the whole session: no final line was printed, the lock stayed held, nothing was published, and the next run reclaimed the lock because its holder process was gone.
29
+
30
+ For a headless run, allow the state directory in the host's own permission config (OpenCode's `opencode.json`, not Systematic's config) before the first run. The state directory is `$XDG_STATE_HOME/systematic/connect`, or `<home>/.local/state/systematic/connect` when `XDG_STATE_HOME` is not set. Use its absolute path:
31
+
32
+ ```json
33
+ { "permission": { "external_directory": { "<state directory>/*": "allow" } } }
34
+ ```
35
+
36
+ With that line, a headless run on OpenCode 1.19.5 ran the whole pipeline and ended `Connect complete`. The researcher's own definition already allows reading outside the project, so the allowed projects need no entry. Systematic never writes this line for the user. If a work file cannot be read or written in a session that is still running, stop with `Connect failed` and say which path the host refused; the lock is released by `publish` with `"abort": true`.
37
+
38
+ ## Outcomes
39
+
40
+ Every run ends with exactly one of these lines as its last line. The reason and the artifact path go on the lines just before the final line. Nothing follows the final line.
41
+
42
+ | Final line | When |
43
+ |---|---|
44
+ | `Connect complete` | `publish` answered `complete`: every project read, every offered rule covered by a complete family, nothing failed, and the run committed. Rules the run was not offered are not a degrade reason, and neither is the stale-citation check reaching its cap: the digest notes it under "Not read or not covered" and the run record keeps the counts, and the outcome is unchanged. Nothing found is still `complete`, labeled "no candidate in searched scope". |
45
+ | `Connect degraded` | `publish` answered `degraded`: something was not read, an offered rule was not covered, a file a candidate cited changed or vanished during the run (`evidence-changed`, `unresolved-source`; the rule of that candidate is then not counted as covered), or a bound on the file inventory, a family or a batch was reached. The digest names what. A degraded run is never proof that nothing is there. |
46
+ | `Connect busy` | `begin` answered `busy`: another run holds the lock, or the holder cannot be verified. Nothing was written and nothing was dispatched. |
47
+ | `Connect failed` | Any other stop: a bad mode token, the helper missing, an unsupported host in headless mode, consent declined, no allowed projects, a malformed batch, or a helper error. Nothing was published. |
48
+
49
+ Copy the final line from the helper's `finalLine` when `publish` answers. For every other stop, print the line from this table.
50
+
51
+ ## Sweep progress
52
+
53
+ A run covers a slice of the rule index, not all of it. The helper offers at most `bounds.maxFamiliesPerRun` times `bounds.maxRulesPerFamily` rules. It offers first the rules never covered, or whose learning changed since they were covered, and then the least recently covered ones. Inside each group it takes the projects in turn, then paths, so a slice spans projects. The order depends only on the index and on what committed runs covered, so the runs in turn sweep the whole index and then start again with the oldest.
54
+
55
+ Rules that are not offered are not a reason to degrade a run. `Connect complete` means the offered slice was fully covered and nothing failed. How much of the index has been covered is sweep progress, and the helper reports it as one line in the digest header and in the publish summary: covered X of Y rules (counting a rule only while its learning has the hash it had when it was covered), how many rules this run covered, and about N runs left in the sweep. A sweep that is finished says so and says the next run starts again with the least recently covered rules.
56
+
57
+ Coverage is kept in the ledger, and only for a committed run: an aborted or crashed run records none. It holds rule ids, hashes and run ids, no text. Coverage of a rule whose learning has disappeared is dropped. `ledger clear` removes coverage with the rest of the ledger, and the sweep starts over.
58
+
59
+ ## Reasons worth naming
60
+
61
+ Print the helper's `reason` as it is, then add the hint when one fits.
62
+
63
+ | Reason | Hint |
64
+ |---|---|
65
+ | `helper-unavailable` | The skill could not start the helper (node is missing or the helper file is gone). Nothing was published. Not a data problem. |
66
+ | `unsupported-host` | The host and version have no observed tool limits. Run interactively and accept the warning, or use a supported host. |
67
+ | `no-allowed-projects` | The allow list is empty or no entry matched a project. List the entries that did not match, with the reason the helper gives for each. |
68
+ | `state-root-refused` | The state directory is unsafe (inside a repository, a symlink, or an allowed project). The helper names why. |
69
+ | `malformed-batch`, `batch-version` | The researcher's answer was not a batch of the right version. The run is over. Run it again. |
70
+ | `batch-missing`, `batch-outside-work-dir` | The skill passed a path the helper does not accept. The run is over. |
71
+
72
+ ## A busy run
73
+
74
+ The lock holder is the host process that started the run. A run that ended without releasing the lock while its host process is still alive, such as a crashed skill run in a live session, stays locked, because the holder looks alive. The lock then needs `ledger unlock`:
75
+
76
+ ```bash
77
+ # Resolve helper scripts relative to this skill's directory.
78
+ SKILL_DIR="<skill directory stated when this skill loads>";
79
+ node "$SKILL_DIR/scripts/connect.mjs" ledger unlock
80
+ ```
81
+
82
+ Offer this only in interactive mode, only after the user says no other run is active. Never run `ledger unlock` on your own for a `busy` answer, and never in headless mode. The one exception is a failed `validate` whose reply does not say `lockReleased: true`: the lock is then the one this run took, no other run can hold it, and the skill runs `ledger unlock` before it stops, in either mode. A lock whose holder process has died is reclaimed by the next run without it.
83
+
84
+ ## Stopping after `begin`
85
+
86
+ Once `begin` answered `begun`, the lock is held. Every stop after that, whatever the reason, ends the run with `publish` and `"abort": true`, which releases the lock and discards the work files. A run that stops without it leaves the lock held until its host process ends.