Document headless error-only runs and resume metadata
A run that fails before inference, with no remote provider or an unknown --resume id, emits a single error event with no session event before it. Each run also rewrites the session metadata with its own cwd and roots, so a resume needs the same --add-dir flags to keep extra roots.
Seto Elkahfi committed
Sep 25, 2026 at 18:10 UTC
090740f9b0c1897bd3f2b6227a743e7f09ee75a8
1 file changed
+6
-1
docs/headless.md
+6
-1
@@ -19,6 +19,8 @@ sigit run "Continue with the fixes" --resume <id>
19
20
The saved metadata includes the primary working directory, additional project roots, and model.
21
This makes the same session discoverable through ACP `session/list` and loadable by an editor.
22
+Each run rewrites that metadata with its own `--cwd` and `--add-dir` values, so a resume records
23
+where the session last ran. Pass the same `--add-dir` flags again to keep extra roots attached.
24
25
Use repeatable `--add-dir <path>` flags for multi-root workspaces. Mutating tools that would ask
26
for interactive permission are denied in headless mode unless granted with
@@ -33,7 +35,10 @@ Pass `--output jsonl` for a machine-readable stdout stream:
35
sigit run "Run the focused tests" --output jsonl --allow-tool run_command
36
```
37
36
-Each line is one JSON object. Every event includes `type` and `session_id`.
38
+Each line is one JSON object. Every event includes `type` and `session_id`. A run that gets as far
39
+as inference starts with a `session` event. A run that fails before that, because no remote
40
+provider is configured or the `--resume` session doesn't exist, emits a single `error` event and
41
+nothing else.
42
43
| Type | Additional fields | Meaning |
44
|---|---|---|