@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable

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 (101) hide show
  1. package/CHANGELOG.md +122 -5
  2. package/NOTICE.md +26 -0
  3. package/builtin/skills/plugin-authoring/SKILL.md +20 -1
  4. package/dist/cli.js +2424 -1237
  5. package/dist/sdk/accounts/accounts.d.ts +26 -20
  6. package/dist/sdk/accounts/accounts.js +100 -63
  7. package/dist/sdk/agents/builtin.js +2 -0
  8. package/dist/sdk/commands/registry.d.ts +7 -0
  9. package/dist/sdk/commands/registry.js +1 -0
  10. package/dist/sdk/core/commandBudget.js +7 -2
  11. package/dist/sdk/core/workspaceWriteOperations.d.ts +24 -0
  12. package/dist/sdk/core/workspaceWriteOperations.js +21 -0
  13. package/dist/sdk/plugins/builtin.js +0 -4
  14. package/dist/sdk/plugins/discover.js +80 -4
  15. package/dist/sdk/plugins/install.js +26 -0
  16. package/dist/sdk/plugins/manifest.d.ts +2 -0
  17. package/dist/sdk/plugins/manifest.js +20 -1
  18. package/dist/sdk/prompt/compile.d.ts +4 -1
  19. package/dist/sdk/prompt/compile.js +8 -21
  20. package/dist/sdk/prompt/reporting.d.ts +2 -0
  21. package/dist/sdk/prompt/reporting.js +282 -0
  22. package/dist/sdk/prompt/standard.d.ts +12 -0
  23. package/dist/sdk/prompt/standard.js +53 -2
  24. package/dist/sdk/sessions/checkpoint.d.ts +7 -0
  25. package/dist/sdk/sessions/checkpoint.js +41 -0
  26. package/dist/sdk/sessions/compactionCheckpoint.d.ts +2 -0
  27. package/dist/sdk/sessions/compactionCheckpoint.js +2 -1
  28. package/dist/sdk/sessions/completionCheck.d.ts +49 -0
  29. package/dist/sdk/sessions/completionCheck.js +143 -0
  30. package/dist/sdk/sessions/continuation.js +1 -1
  31. package/dist/sdk/sessions/contracts.d.ts +97 -1
  32. package/dist/sdk/sessions/contracts.js +17 -0
  33. package/dist/sdk/sessions/goal.d.ts +145 -0
  34. package/dist/sdk/sessions/goal.js +405 -0
  35. package/dist/sdk/sessions/goalLoop.d.ts +37 -0
  36. package/dist/sdk/sessions/goalLoop.js +125 -0
  37. package/dist/sdk/sessions/goalPrompts.d.ts +4 -0
  38. package/dist/sdk/sessions/goalPrompts.js +93 -0
  39. package/dist/sdk/sessions/planMode.d.ts +31 -0
  40. package/dist/sdk/sessions/planMode.js +48 -3
  41. package/dist/sdk/sessions/registry.d.ts +6 -1
  42. package/dist/sdk/sessions/registry.js +4 -4
  43. package/dist/sdk/sessions/runStore.js +1 -0
  44. package/dist/sdk/sessions/runner.d.ts +9 -0
  45. package/dist/sdk/sessions/runner.js +65 -13
  46. package/dist/sdk/sessions/sessions.d.ts +10 -0
  47. package/dist/sdk/sessions/sessions.js +87 -10
  48. package/dist/sdk/sessions/stopGate.d.ts +78 -0
  49. package/dist/sdk/sessions/stopGate.js +143 -0
  50. package/dist/sdk/sessions/subagentService.d.ts +2 -0
  51. package/dist/sdk/sessions/subagentService.js +1 -1
  52. package/dist/sdk/sessions/workSlice.d.ts +61 -12
  53. package/dist/sdk/sessions/workSlice.js +102 -33
  54. package/dist/sdk/terminal/controller.d.ts +2 -2
  55. package/dist/sdk/terminal/controller.js +14 -4
  56. package/dist/sdk/terminal/credentialStore.d.ts +4 -0
  57. package/dist/sdk/terminal/credentialStore.js +33 -0
  58. package/dist/sdk/terminal/piExtension.d.ts +2 -1
  59. package/dist/sdk/terminal/piExtension.js +160 -27
  60. package/dist/sdk/terminal/terminals.js +27 -4
  61. package/dist/sdk/terminal/tui/commands.d.ts +2 -0
  62. package/dist/sdk/terminal/tui/commands.js +3 -0
  63. package/dist/sdk/terminal/tui/goalCommand.d.ts +19 -0
  64. package/dist/sdk/terminal/tui/goalCommand.js +83 -0
  65. package/dist/sdk/terminal/tui/planMode.d.ts +1 -1
  66. package/dist/sdk/terminal/tui/planMode.js +1 -1
  67. package/dist/sdk/terminal/tui/runtime.d.ts +3 -0
  68. package/dist/sdk/terminal/tui/runtime.js +21 -4
  69. package/dist/sdk/tools/askUser.js +1 -1
  70. package/dist/sdk/tools/todo.js +2 -1
  71. package/dist/terminal-opentui.js +1740 -627
  72. package/dist/terminal-pi.js +996 -407
  73. package/docs/architecture/02-sessions-and-runs.md +47 -11
  74. package/docs/architecture/04-prompt.md +83 -16
  75. package/docs/architecture/06-plugins-and-capabilities.md +16 -1
  76. package/docs/architecture/07-tools-and-gate.md +7 -2
  77. package/docs/architecture/09-accounts-and-connectors.md +9 -0
  78. package/docs/architecture/10-server-protocol.md +13 -0
  79. package/docs/architecture/11-terminal.md +38 -12
  80. package/docs/architecture/proposals/PROP-0041-bounded-work-slices.md +2 -0
  81. package/docs/decisions/ADR-0008-flexible-reporting-guidance.md +3 -0
  82. package/docs/decisions/ADR-0063-unfinished-work-handoffs.md +2 -0
  83. package/docs/decisions/ADR-0068-scope-and-completion-report.md +60 -0
  84. package/docs/decisions/ADR-0069-stop-gate-and-finish.md +130 -0
  85. package/docs/decisions/ADR-0070-terminal-slice-continuation.md +46 -0
  86. package/docs/decisions/ADR-0071-completion-check.md +104 -0
  87. package/docs/decisions/ADR-0072-codex-prompts-and-goal.md +105 -0
  88. package/docs/decisions/ADR-0073-large-reporting-prompt.md +84 -0
  89. package/docs/parity.md +4 -1
  90. package/docs/releases/1.3.1-unstable.9.md +54 -0
  91. package/docs/releases/1.4.0-unstable.md +18 -0
  92. package/docs/releases/README.md +1 -1
  93. package/docs/study/00-index.md +10 -0
  94. package/docs/study/STUDY-0004-turn-end-controls.md +123 -0
  95. package/docs/study/STUDY-0005-skill-installation-guidance.md +146 -0
  96. package/docs/study/STUDY-0006-reporting-prompts.md +81 -0
  97. package/docs/study/arms/04-skills.md +6 -0
  98. package/docs/terminal-tui.md +17 -7
  99. package/package.json +1 -1
  100. package/dist/sdk/tools/checkpoint.d.ts +0 -27
  101. package/dist/sdk/tools/checkpoint.js +0 -154
@@ -300,7 +300,12 @@ is approved but remains in progress; no completed cross-surface catalog is impli
300
300
  commands. Generic browser actions and connected-app calls remain unavailable in plan mode. The
301
301
  gate refuses unsafe calls before approvals, and the service rechecks before launch. The terminal activates plan-eligible
302
302
  tools only for a plan request, then restores its normal set. Provider-cache effects of the tool-list
303
- difference are not assumed (page 04, `INV-PRM-8`).
303
+ difference are not assumed (page 04, `INV-PRM-8`). Pi records a tool-set change only with the next
304
+ request, so the terminal brackets each plan request with `xingular-plan-tools` entries (`begin`
305
+ carries the normal set it replaced, then `end`). Whenever Pi rebuilds the active tools from the
306
+ transcript (a new runtime, resume, switch, fork or tree navigation), `normalToolsForBranch` returns
307
+ the bracketed normal set if the last recorded set is a plan's, so a plan never leaks into normal
308
+ mode.
304
309
  - **INV-RUN-9** Subagent results reach the parent at native turn boundaries, at most once
305
310
  automatically (typed receipts in native history). A parent joins outstanding children before it
306
311
  completes.
@@ -319,24 +324,55 @@ is approved but remains in progress; no completed cross-surface catalog is impli
319
324
  available with `workSlice.maxNewTokens`, counted on new input, cache writes and output and never on
320
325
  the cached prefix: a few large reads pass any small cap before useful work, so the tool calls and
321
326
  the clock are the bound and the token count is only a ceiling for whoever asks for one. At the
322
- limit the guard refuses the next tool call. When `checkpoint_write` is available, it requests a
323
- checkpoint and leaves handoff calls callable; otherwise a plan-research child must stop with a
324
- concise partial research report, and the runner derives a checkpoint from run evidence. A
325
- non-handoff tool call after the refusal ends the reply. A budget-ended reply is `interrupted` with
326
- terminal reason `slice_complete` (ADR-0053).
327
+ limit the guard refuses the next tool call and asks the model to stop and report where it is; the
328
+ harness then writes the checkpoint itself from the reply's files, checks and todo list (the model
329
+ has no checkpoint tool since ADR-0069). A non-handoff tool call after the refusal ends the reply. A
330
+ budget-ended reply is `interrupted` with terminal reason `slice_complete` (ADR-0053), unless it
331
+ continues: a headless run as a new run (`continueSlice`), a terminal reply in place as its next
332
+ slice (ADR-0070), both up to `maxSlices` and never after a fruitless or blocked slice. The budget
333
+ covers the whole reply: Pi emits `agent_start` for every continuation (a stop-gate nudge, delivered
334
+ subagent results, a plan repair), so the guard starts a new slice only on a person's message.
327
335
  No call is refused for repeating: identical calls, a Bash check that keeps failing and repeated
328
336
  `edit`/`write` results on one path are allowed as often as the work needs, because a distinct read
329
337
  or another edit is not evidence of a loop. `todo_write` counts toward the tool-call budget and is
330
338
  otherwise unconstrained. Third-compaction thrash detection remains: three context compactions in
331
- one reply end it with the same handoff request. Plan-research children without `checkpoint_write`
332
- receive the configured bound without a new capability and do not auto-continue. A new run
339
+ one reply end it with the same handoff request. Plan-research children receive the configured bound
340
+ without a new capability and do not auto-continue. A new run
333
341
  continues it only up to the policy's slice cap, only after a slice that changed a file, passed a
334
342
  check or recorded a finished item, and never after a checkpoint that is `blocked`. A run may turn
335
343
  the guard off with `workSlice.enabled: false`, and a launch may set `XINGULAR_WORK_SLICE=off` for
336
344
  every run in that process; with it off a reply has no boundary — no checkpoint, no continuation —
337
- and ends only when the model stops or a person interrupts.
338
- - **INV-RUN-14** A run event stream carries `checkpoint` (the handoff `checkpoint_write` records or
339
- the harness derives from the run's own evidence when the model wrote none) and `heartbeat`
345
+ and ends only when the model stops or a person interrupts. A reply the model ends on its own is
346
+ subject to the todo gate (INV-RUN-15) and, in a goal, the goal loop (INV-RUN-16); a continuation carries the todo it left (`continuation.ts`).
347
+ - **INV-RUN-15** A reply may not quietly end while its own todo list has open items (ADR-0069,
348
+ ADR-0072). In an attended top-level run (not plan, command, automatic, subagent or other related
349
+ runs) the **todo gate** acts at Pi's `agent_before_settle` boundary, unless the reply failed,
350
+ aborted or was ended by the slice guard: an item still `pending` or `in_progress` sends the reply
351
+ back with a displayed `xingular-stop-gate` message naming the open items and saying that the list
352
+ shows progress, not the limit of the work. No model is asked. A cap of three nudges per reply
353
+ applies, and no nudge follows one that produced no tool call other than `todo_write` or
354
+ `session_name`. Each nudge is an `extension.notice` from `stop-gate`. A reply settles `completed`
355
+ when no item is open; otherwise it is `interrupted` with terminal code `unfinished` and a
356
+ harness-written checkpoint, and a person continues it. **No model judges an ordinary reply**
357
+ (ADR-0072 removed ADR-0071's every-reply completion check); completion pressure there is the prompt
358
+ (`04-prompt.md`). `XINGULAR_STOP_GATE=off` at launch switches the gate off.
359
+ - **INV-RUN-16** A goal is the person's opt-in long run (ADR-0072). Only a person's own top-level run
360
+ carries one (`sessions.run` `goal`, or `/goal` in the terminal); never a plan, command, unattended
361
+ or child run. While its status is `active`, a reply that would end continues in place (the goal
362
+ loop, `sessions/goalLoop.ts`) with the continuation prompt, counting a round. Statuses are
363
+ `active | paused | blocked | usage_limited | budget_limited | complete`; the person sets, edits,
364
+ pauses, resumes and clears, the system limits (`budget_limited` at 30 rounds or 8 hours by default;
365
+ `usage_limited` on a provider usage limit; `blocked` after three automatic rounds with no activity,
366
+ three with only failed commands, or a provider error), and the model may only claim `complete`,
367
+ report `blocked` after the same blocker on three consecutive goal turns, or `paused` at the person's
368
+ request. A `complete` is a claim: at the next settle the same model, at low effort and with a fresh
369
+ context, checks it against the objective and the transcript; `done` completes the goal, `continue`
370
+ keeps it active with the reason, and no model, an error or an unreadable answer accepts it. The
371
+ loop never stops a goal for a round without a tool call alone. A goal that ends `blocked` settles
372
+ the run `needs_person`; one that ends paused, limited or stalled settles it `unfinished`. The run
373
+ record keeps the goal as `goalMode`. `XINGULAR_COMPLETION_CHECK=off` accepts every claim unchecked.
374
+ - **INV-RUN-14** A run event stream carries `checkpoint` (the handoff the harness derives from the
375
+ run's own evidence; runs written before ADR-0069 may hold one the model wrote) and `heartbeat`
340
376
  (steps, elapsed time, last tool, compactions, slice, and the call budget). Every live reply emits a
341
377
  heartbeat every 30 seconds, terminal replies included. A heartbeat older than five minutes while
342
378
  the owner process lives marks the run `interrupted` with reason `stalled`; a run that never emitted
@@ -76,26 +76,93 @@ guidance for the effective tools. Terminal preparation defaults to standard sect
76
76
  attributed add-on and task context, not a duplicate standard role or connection policy (PROP-0040).
77
77
 
78
78
  Budgets (characters): variant sections 30,000 each (already capped at save, so never cut here);
79
- references 12,000; Wiki pointer 2,500; tools 8,000; reporting 2,000; application sections their
80
- own `budget`.
79
+ references 12,000; Wiki pointer 2,500; tools 8,000; reporting 18,000 (ADR-0073); the
80
+ standard session's sections: role 1,400, autonomy 2,600, permission 1,800, steering 2,000, writing
81
+ 1,900 (ADR-0072); application sections their own `budget`.
81
82
 
82
83
  ## Reporting
83
84
 
84
85
  Every pack ends with the harness's `reporting` section ("Reporting your work",
85
- `REPORTING_GUIDANCE` in `prompt/compile.ts`). It is fixed text that shapes the final reply: lead
86
- with the outcome rather than the steps taken to reach it, cover the most important information, and
87
- use as much structure as the answer needs. Descriptive headings, lists and tables may help explain
88
- the outcome; no fixed list of report headings is required. When work remains unfinished, state the concrete decision the person
89
- must make or the next action and its owner for each material blocker, without inventing a human
90
- decision. When a concrete verification requires a person because the agent
91
- could not perform or observe it, the optional **Need human inspection** heading says what remains
92
- unverified, why, and the specific check the person should make. Report only checks actually run,
93
- with their results. Markdown tables are used where they help compare options or present repeated
94
- fields or check results; any format the person, application or current mode asks for takes
95
- precedence. The section names no application, is never dynamic, and is never cut. See
96
- [PROP-0001](proposals/PROP-0001-reporting-section.md),
97
- [PROP-0004](proposals/PROP-0004-flexible-reporting-guidance.md), and
98
- [ADR-0008](../decisions/ADR-0008-flexible-reporting-guidance.md).
86
+ `REPORTING_GUIDANCE` in `prompt/reporting.ts`, imported by `prompt/compile.ts`). It is fixed text
87
+ that shapes the final reply: lead with the outcome rather than the steps taken to reach it, and
88
+ cover only what the person needs to act. The section defines content blocks, not a fixed heading
89
+ list ([ADR-0008](../decisions/ADR-0008-flexible-reporting-guidance.md),
90
+ [ADR-0073](../decisions/ADR-0073-large-reporting-prompt.md)): a change carries four required blocks
91
+ — outcome, what changed, how to test, and what to do next — while a question stays one to three
92
+ sentences and research carries only the blocks with content. How to test gives numbered steps with
93
+ exact commands or URLs, the expected result, what the agent already ran, and what the person must
94
+ run; what to do next names the person's action or says "Nothing needed". Optional blocks cover work
95
+ beyond the request (with why), departures from a plan (what and why), work that needs a person's
96
+ check (what is unverified, why, and the exact check), and open questions. Headings are the model's
97
+ choice — "How to test", "Try it" and "Verify" name the same block — and a heading must name its
98
+ content. The section ships five worked examples and an anti-pattern table, uses tables for files,
99
+ checks and comparisons, and caps a change at about 20–60 lines. A person, application or mode format
100
+ takes precedence. The section names no application, is never dynamic, and is never cut; its budget is
101
+ 18,000 characters (ADR-0073).
102
+
103
+ ## When a reply may end
104
+
105
+ A reply ends when the request is done, when the work-slice guard ends it (INV-RUN-13), when a person
106
+ interrupts, or when the work cannot continue without the person. An open todo item, a passing check,
107
+ a partial result or a long task is not such a reason. An ordinary reply is held to this by two
108
+ things (ADR-0069, ADR-0072): the words below, and the todo gate (INV-RUN-15), which sends back a
109
+ reply that ends while its todo list has open items. **No model judges an ordinary reply**; a goal's
110
+ completion claim is the one thing a model checks (INV-RUN-16). A reply that settles with work left is
111
+ `interrupted` (`unfinished`, or `needs_person` for a blocked goal), never `completed`.
112
+
113
+ The words decide what the model does before the gate has to act, and none of them may read as
114
+ permission to stop with work left. A person's own session (`launch.standard`, `prompt/standard.ts`)
115
+ reads five stable sections adapted from OpenAI Codex's gpt-6.1-sol instructions (Apache-2.0, see
116
+ `NOTICE.md`), the same for every model so the terminal and a host read the same text (INV-PAR-1):
117
+
118
+ - `role` — the assistant's job, and the extra work it does without asking (the obvious adjacent
119
+ step, what the work exposes, the check it needs) inside the working folder and away from what a
120
+ person must decide (a deploy, a secret, remote data, money). Extra work and departures from the
121
+ plan are allowed on those terms and reported at the end.
122
+ - `autonomy` — bias to action; persist until the intended goal is complete; "can you...", "help
123
+ me..." are instructions; no partial or "helpful enough" solution; an open todo item, a passing
124
+ check, a partial result or a long task is not a reason to end the turn; the todo list shows
125
+ progress and the request is the scope; which decisions are the agent's own; a document the request
126
+ points to is the request; a question the request or files already answer is not a question for the
127
+ person; the only reasons to stop, one of them a fix to a test or error that does not come from
128
+ this session's work (and then say exactly what is needed).
129
+ - `permission` — authorisation persists; finish the authorised work first so that approval is the
130
+ last step; no permission for reversible, read-only or already authorised work; a test or error
131
+ that does not come from this session's work is reported, not fixed, unless the person asks (a
132
+ failure is this session's work when the agent's changes caused it), and is kept off the todo
133
+ list; no messages to other people unless asked; when the agent must ask, it says why and where
134
+ the requirement comes from.
135
+ - `steering` — a new message steers the active task; a correction means "fix it"; compaction does
136
+ not end the task, and work across compactions is one chain.
137
+ - `writing` — plain words, the outcome first, evidence and limits, routine verification summarised,
138
+ no AI-slop phrases, no "X, not Y" contrast, no invented labels, no needless apology.
139
+
140
+ Other fixed text that shapes the end of a reply:
141
+
142
+ - `TODO_GUIDANCE` (`tools/todo.ts`): the list is progress, not scope; the request, and any document
143
+ it points to, is the scope; add steps as the work shows them; list a handoff's steps instead of one
144
+ "remaining work" item; before ending, compare the request, not the list, with what is done and
145
+ checked. An open step is work to do in this reply, not something to report.
146
+ - `reporting` (`REPORTING_GUIDANCE`): opens with "Reporting is for work that is finished or genuinely
147
+ blocked". When work is not finished, the first line says so, gives the specific reason and names
148
+ the next step. The final reply is self-contained, says what could not be done or verified, never
149
+ closes with an "If you want..." offer, and stays near 60 lines. Its `## What would make this
150
+ complete` heading applies only when the work stopped short and says never to stop early to write
151
+ it.
152
+ - `ask_user` (`tools/askUser.ts`): for a decision the request and files do not answer, never for
153
+ permission to do work inside the request; no answer means continue with best judgment (Codex's
154
+ Default-mode rule).
155
+ - In a person's own session the `Progress` tool group says that a reply with open items is sent back.
156
+ There is no tool to stop "on purpose": ADR-0069 removed `checkpoint_write` and ADR-0071 removed
157
+ `finish`. The only tool that ends work is `update_goal` in a goal the person started (INV-TOOL-9).
158
+
159
+ All of these are fixed text in the stable prefix, so changing them changes the cached prefix once.
160
+ A live terminal session keeps the pack, and the extension code, it started with; a harness update
161
+ reaches it only when the session restarts.
162
+
163
+ A goal's text (`sessions/goalPrompts.ts`, adapted from Codex's `ext/goal/templates`) is not in the
164
+ prefix: the continuation, round-cap and edit prompts ride as hidden user messages, with the
165
+ objective escaped and wrapped as data (INV-PRM-2).
99
166
 
100
167
  ## Delivery
101
168
 
@@ -53,7 +53,22 @@ callable result for one run.
53
53
  route to another owner's template or guess a default (ADR-0061).
54
54
  A package without a `package.json` name is named, described and versioned by the first of
55
55
  `plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, so an agent plugin
56
- written for other harnesses installs as it is.
56
+ written for other harnesses installs as it is. The first of those manifests that declares
57
+ `skills` (a path or a list of paths) also brings those skill folders as package skill
58
+ contributions, so a plugin laid out for another harness contributes the skills it declares. A
59
+ declared path must stay inside the package, and a symlinked skill folder is skipped. Pi's own
60
+ `skills/` folder and `package.json` manifest take precedence, and a package whose settings entry
61
+ names skill patterns is left to that filter.
62
+ - **Skill installation routes.** A skill reaches a run as text from the working folder's `.pi/skills`
63
+ or `.agents/skills` (walking up to the repository root), the OS user's `~/.agents/skills`, the
64
+ state's `accounts/_shared/pi/skills`, a package's `skills` or a foreign manifest's declared paths,
65
+ or the pinned variant's `skills`. A model may write the first two; `~/.agents` is outside the
66
+ workspace, so a write there needs the person's approval. Variant, library, Hub and package
67
+ installs change committed state and are person acts (`/skills`, `/components`, `/hub`,
68
+ `/plugins`). A variant holds `SKILL.md` and flat `scripts/` files only. `plugins.install` takes a
69
+ package address: a GitHub or GitLab `tree`/`blob` page address is refused with the repository
70
+ address and these routes. The install guidance lives in the release-owned `plugin-authoring`
71
+ skill, not the always-on prompt ([STUDY-0005](../study/STUDY-0005-skill-installation-guidance.md)).
57
72
  - **Package subagent profiles.** An installed package's agents folder (`agents/` unless
58
73
  `harness.agents` names another) brings each Markdown file whose frontmatter has a `name` and a
59
74
  `description` as an `agent` contribution (at most 50). It is text: it needs no trust and follows
@@ -147,8 +147,13 @@ beside the choices (INV-RC-3, INV-RC-4).
147
147
 
148
148
  - **INV-GATE-1** Every tool call of every run passes the gate. No tool source bypasses it,
149
149
  including extension-registered tools (which ask before every call) and the initial Bash command.
150
- - **INV-TOOL-9** `checkpoint_write` records one bounded handoff for the active run and is read-only
151
- and plan-safe: no field changes files, and the record is the `checkpoint` run event (PROP-0041).
150
+ - **INV-TOOL-9** The model has no tool that ends or hands off its own work (ADR-0071, ADR-0072):
151
+ neither `checkpoint_write` (PROP-0041, removed by ADR-0069) nor `finish` (ADR-0069, removed by
152
+ ADR-0071) exists. The one exception is `update_goal` in a goal the person started: it is offered
153
+ only while a goal exists, its `complete` is only a claim that the harness checks (INV-RUN-16), and
154
+ its `paused` needs the person's word. The model cannot create, resume or limit a goal. When a
155
+ reply stops, the harness decides how it settled (INV-RUN-15) and writes the checkpoint from the
156
+ run's evidence.
152
157
  - **INV-TOOL-10** Bash keeps one command budget on every surface: 120 seconds when the call says
153
158
  nothing, 300 seconds as the ceiling without a `reason`, 900 seconds as the maximum, and a timeout
154
159
  returns the partial output with a narrowing instruction instead of blocking the reply.
@@ -60,6 +60,15 @@ skills, prompts, rules and Pi packages.
60
60
  - **INV-ACC-4** A terminal's `/accounts` goes through the session socket's `accounts.*` calls, and
61
61
  every one needs the session's control key. A command the model runs in the shell cannot make
62
62
  an account change.
63
+ - **INV-ACC-5** A credential has one copy. A terminal's Pi keeps no `auth.json`: it reads its own
64
+ account's credentials with `accounts.credentials.read`/`list`, and a refresh or sign-in holds the
65
+ store's cross-process lock from `accounts.credentials.lease` to `accounts.credentials.commit`
66
+ (`terminal/credentialStore.ts`, at most 20 seconds, then the lease lapses unchanged). Like every
67
+ `accounts.*` call they need the control key, so the model's shell never sees a token. Two copies of
68
+ a rotating refresh token, each under its own lock, let the second refresh send a spent token and
69
+ fail with `invalid_grant`. An `auth.json` a terminal of an older version left is folded in under the
70
+ lock, a newer stored token never replaced, and removed once no other process has a terminal on the
71
+ account.
63
72
  - **INV-MCP-1** Connector secrets live in the `SecretStore`; `connections.json` holds no secret.
64
73
  Run events and traces are redacted before they are stored or shown.
65
74
  - **INV-MCP-2** A session reaches only the connections its scope and the policy allow, and loses
@@ -79,6 +79,19 @@ harness → host { v: 1, id, call, params } host → harness { v: 1
79
79
  - The run-event stream adds `checkpoint` (the bounded handoff) and `heartbeat` (steps, elapsed time,
80
80
  last tool, compactions, slice, call budget). Hosts must accept both; an unknown event type is still
81
81
  relayed in order (INV-RUN-3).
82
+ - `terminalCode` gains `needs_person` and `unfinished` (ADR-0069, ADR-0072): a reply that settled with
83
+ work left — `needs_person` when the run's goal ended `blocked`, `unfinished` when todo items stayed
84
+ open or a goal was paused, stalled or limited. Both are `interrupted`, carry a `checkpoint`, and
85
+ are not auto-continued; a host should offer the person Continue, as it does for `slice_complete`.
86
+ Stop-gate nudges arrive as `extension.notice` events with `extension: 'stop-gate'`.
87
+ - `sessions.run` accepts `goal { objective, rounds?, hours? }` (ADR-0072, INV-RUN-16) for a person's
88
+ own top-level run; it is refused with `invalid_request` for a plan, command, unattended or child
89
+ run, or an empty or over-long (4,000 character) objective. The objective is the request, and the
90
+ run continues in place while the goal is active. Goal rounds, claim checks and stops arrive as
91
+ `extension.notice` events with `extension: 'goal'`; a claim check's model request is one more
92
+ `usage.updated` request. Run records carry `goalMode` (`goalId`, `objective`, `status`, `limits`,
93
+ `rounds`, `timeUsedSeconds`, `claimed`, `lastReason`) while a goal exists; `goal` stays the
94
+ request text. A goal active at a work-slice boundary is carried into the continuation run.
82
95
  - Run streams also carry `tool.refused` with the call id, name, refusal code and bounded reason.
83
96
  Run records expose nullable `terminalCode`; `terminalReason` remains descriptive text. Older
84
97
  records and events may omit the code. Trajectory search exposes both fields (pages 02 and 08).
@@ -58,7 +58,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
58
58
  (ADR-0064). With no usable saved selection, Pi's own fallback message stands.
59
59
  - Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
60
60
  shared tool alongside its read-only set and restores the normal set on success, failure or
61
- interruption. The question blocks until answered, then planning continues in the same run. There
61
+ interruption, and again after any rebuild from the transcript (page 02, `INV-RUN-8`). The question blocks until answered, then planning continues in the same run. There
62
62
  is no terminal-only question alias (PROP-0040).
63
63
  - The approved plan outcome contract on page 02 applies equally to the terminal and server:
64
64
  only `plan_ready` offers a plan card and Implement; `blocked` reports unavailable required input
@@ -377,15 +377,38 @@ release.
377
377
  Terminal tool-gate and work-slice refusals are relayed as `tool.refused` events with a code and reason; the original refusal text remains the tool response. Interrupted terminal runs record stop codes for work-slice limits, user abort, stalls and terminal closure.
378
378
 
379
379
  Terminal replies carry the same work-slice guard as structured runs: 320 tool calls or 60 minutes,
380
- with no new-token limit by default (PROP-0044), then a refusal that asks for `checkpoint_write`. The
381
- extension registers the shared tool and sends it as `checkpoint` telemetry, which the controller
382
- records as `checkpoint` on the
383
- active run, so an App reading the same session sees the handoff. Terminal replies are not
384
- auto-continued: at the boundary the person decides, which is what the terminal's own turn model
385
- already does. The run record says `interrupted` with terminal reason `slice_complete`, so a host can
386
- continue it; a checkpoint card in the transcript is not built yet (PAR-004). Start the terminal with
387
- `XINGULAR_WORK_SLICE=off` to launch a reply with no
388
- boundary at all; it is not persisted, so the next launch without it restores the guard.
380
+ with no new-token limit by default (PROP-0044), then a refusal that asks the model to stop and report
381
+ where it is. Terminal replies also carry the todo gate (INV-RUN-15, ADR-0069, ADR-0072): the
382
+ extension sends a reply that ends with open todo items back, up to three nudges, each `notice`
383
+ telemetry recorded as `extension.notice`, and at settle sends a harness-written `checkpoint` and the
384
+ `needs_person` or `unfinished` code, which the controller records on the active run, so an App
385
+ reading the same session sees the handoff. No model judges an ordinary reply. Plan replies are not gated. A reply that
386
+ reaches its budget after doing work continues in place as its next slice (ADR-0070): a
387
+ `xingular-slice-continue` message in the same run, a checkpoint and a notice per boundary, up to
388
+ `maxSlices` (8). A fruitless, blocked, failed, aborted or plan slice, or one whose todo items are all
389
+ done, is not continued; the reply then settles `interrupted` with terminal reason `slice_complete`
390
+ so the person or a host can continue it. A checkpoint card in the transcript is not built yet
391
+ (PAR-004). Start the terminal with `XINGULAR_WORK_SLICE=off` to launch a reply with no boundary at
392
+ all, or with key=value pairs such as `maxToolCalls=15,maxSlices=3` for a smaller policy; neither is
393
+ persisted, so the next launch without it restores the defaults.
394
+
395
+ ## `/goal` (ADR-0072, INV-RUN-16)
396
+
397
+ `/goal <objective>` sets the session's goal and starts work at once; `--rounds N` and `--hours H`
398
+ before the objective set this goal's caps (30 rounds, 8 hours by default). Bare `/goal` shows the
399
+ status (status, objective, rounds, time used, last check, and the commands that apply). `/goal edit`
400
+ asks for a new objective (the same goal, its usage kept), `pause` stops a running reply and keeps the
401
+ goal, `resume` continues it, `clear` removes it. A subcommand matches only as the whole argument, so
402
+ "/goal pause now" is an objective. Setting a goal while an unfinished one exists asks first. Esc or
403
+ Ctrl-C on a running goal pauses it, as in Codex. The status bar shows `Pursuing goal (2m, round
404
+ 3/30)`, `Goal paused (/goal resume)`, `Goal stalled (/goal resume)`, `Goal hit usage limits (/goal
405
+ resume)`, `Goal unmet (...)` or `Goal achieved (...)`.
406
+
407
+ The goal lives in the Pi session as a `xingular-goal-state` entry, so a reopened conversation shows
408
+ it, as `paused`: nothing resumes by itself. The model gets `get_goal` and `update_goal` only while a
409
+ goal exists (INV-TOOL-9). The goal loop is a second extension after the todo gate and before slice
410
+ continuation; a goal's slices continue even when every todo item is done. `/goal` is a `session`
411
+ command that uses `sessions.run` with `goal` (page 10); in plan mode the loop stays silent.
389
412
 
390
413
  ## Liveness and a reply that stops working (INV-RUN-14, ADR-0054)
391
414
 
@@ -397,9 +420,12 @@ terminal reply that stopped reporting by the same five-minute rule as a structur
397
420
  A heartbeat proves the turn is alive, not that it is working. A reply that produces no event other
398
421
  than a heartbeat for fifteen minutes — the state a model request that never returns leaves it in —
399
422
  is ended: the controller queues the same `interrupt` command the person's Esc queues, the native turn
400
- aborts, and the run records `interrupted` with reason `stalled`. A reply whose oldest running tool
423
+ aborts, and the run records `interrupted` with reason `stalled`. Pi's abort reports back through
424
+ `terminal.interrupt` as Esc does; the controller passes that interrupt on as `stalled`, not
425
+ `user_abort`, when the stall watch asked for it. A reply whose oldest running tool
401
426
  has run for thirty minutes ends the same way, and a reply waiting on an approval or question is never
402
- cut short.
427
+ cut short. An interrupt, a stall included, also ends a settling reply's wait for its subagents
428
+ (`terminal.subagents.delivery`).
403
429
 
404
430
  ## Subagent activity monitor
405
431
 
@@ -9,6 +9,8 @@ affects: [INV-RUN-2, INV-RUN-3, INV-RUN-4, INV-RUN-12, INV-PRM-1, INV-PRM-2, INV
9
9
 
10
10
  # PROP-0041: Bounded work slices, a durable checkpoint, and a stall guard
11
11
 
12
+ > **Amended by [ADR-0069](../../decisions/ADR-0069-stop-gate-and-finish.md):** the model no longer writes the checkpoint — `checkpoint_write` is removed and the harness writes it from the reply's evidence; the slice budget now covers the whole reply, including Pi's own continuations.
13
+
12
14
  ## Problem
13
15
 
14
16
  A single reply can run for hours. Two measured sessions (STUDY-0003) ran 114 and 75 minutes in
@@ -5,9 +5,12 @@ status: accepted
5
5
  created: 2026-10-21
6
6
  updated: 2026-10-21
7
7
  supersedes: ADR-0007
8
+ amended_by: ADR-0073
8
9
  ---
9
10
  # ADR-0008 — Flexible reporting guidance with optional human inspection
10
11
 
12
+ > **Amended by [ADR-0073](ADR-0073-large-reporting-prompt.md):** flexible headings stand; the `reporting` section now names required content blocks and ships worked examples, and the later fixed headings (ADR-0068) are gone.
13
+
11
14
  ## Context and decision
12
15
 
13
16
  ADR-0007 added stable, harness-owned guidance for final replies, but its fixed heading list could
@@ -7,6 +7,8 @@ updated: 2026-10-30
7
7
  ---
8
8
  # ADR-0063 — Actionable handoffs for unfinished work
9
9
 
10
+ > **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** this guidance now applies only when the work stopped on a blocker or a decision (`finish`), never as a way to end a reply with work left.
11
+
10
12
  ## Context and decision
11
13
 
12
14
  A reply can accurately report blockers yet leave the person unable to tell what decision or
@@ -0,0 +1,60 @@
1
+ ---
2
+ id: ADR-0068
3
+ title: Scope of the work and two required completion headings
4
+ status: superseded
5
+ created: 2026-10-30
6
+ updated: 2026-11-01
7
+ superseded_by: ADR-0073
8
+ supersedes: partial — ADR-0008
9
+ ---
10
+ # ADR-0068 — Scope of the work and two required completion headings
11
+
12
+ > **Superseded by [ADR-0073](ADR-0073-large-reporting-prompt.md):** the two required headings and the fixed-label rule are replaced by content blocks and flexible headings. The scope rule in the `role` paragraph stands.
13
+
14
+ > **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** `## What would make this complete` applies only when the work stopped short (blocked, needing the person, or handed back by the guard), and the deferred runner feature is now the stop gate.
15
+
16
+ ## Context and decision
17
+
18
+ ADR-0008 removed the fixed heading list from the `reporting` section and kept every heading
19
+ optional. Two problems followed from a prompt that only described output:
20
+
21
+ 1. Every run of the last seven days that ended with work left (207 of 822, 25 %) did so at a median
22
+ of 17 tool calls; the model treated the literal request as the whole assignment
23
+ (`outputs/diagnoses/2026-10-30-sweep.md`). Nothing in the prompt said the work extends to what the
24
+ request implies.
25
+ 2. A person reading the final reply could not tell what had been done beyond their request, nor what
26
+ would finish the run. `README`-style prose hid both.
27
+
28
+ The `role` paragraph of a standard session now states the scope of the work — the job the request
29
+ implies, not only its literal words, inside the working folder and away from what a person must
30
+ decide (a deploy, a secret, remote data, money), without asking first inside those bounds — and the
31
+ `reporting` section requires two headings when they apply:
32
+
33
+ - `## Beyond what you asked` — anything done beyond the request, each piece with why the work needed it.
34
+ - `## What would make this complete` — the concrete remaining steps in order, naming the ones only
35
+ the person can decide.
36
+
37
+ `REPORTING_BUDGET` rises from 2,000 to 2,400 characters to hold them without cutting
38
+ (`prompt/compile.ts`).
39
+
40
+ ## Consequences
41
+
42
+ - A run may do and report adjacent work that the person did not name; the second heading is what
43
+ makes that auditable and rejectable rather than silent.
44
+ - The stable prefix changes once per session for the three texts (`role`, `reporting`,
45
+ `TODO_GUIDANCE`). Measured with real requests only, under INV-PRM-8.
46
+ - Applications bundling the harness need a rebuild before any new session sees the wording; an
47
+ existing session keeps the prefix it compiled (observed: `context.json` `compiledAt` 16:33:36Z
48
+ reused by a run at 17:21Z).
49
+ - No stored data or protocol changes. Bounded autonomy is still enforced by the tool gate and the
50
+ workspace boundary; the prompt does not grant new reach.
51
+
52
+ ## Alternatives considered
53
+
54
+ - Keep every heading optional (ADR-0008 as it stood): rejected — the two facts above were invisible
55
+ in the reply, so the person could not see either the extra work or the gap.
56
+ - One combined heading ("Summary"): rejected — extra work and remaining work are different decisions
57
+ for the person, and merging them hides which is which.
58
+ - Make autonomy a runner feature (continue when a todo is open): deferred, not rejected. The prompt
59
+ is the cheapest lever and was not yet in effect; `docs/research/2026-10-30-turn-end-controls.md`
60
+ records what other harnesses do and when a stop-hook style continuation is worth adding.
@@ -0,0 +1,130 @@
1
+ ---
2
+ id: ADR-0069
3
+ title: A stop gate and a finish tool; the model's checkpoint tool is removed
4
+ status: accepted
5
+ created: 2026-10-31
6
+ updated: 2026-10-31
7
+ supersedes: partial — PROP-0041 (the model-written checkpoint), ADR-0068 (when the completion heading applies), ADR-0063 (scope of the unfinished-work guidance)
8
+ related:
9
+ - STUDY-0004
10
+ - ADR-0068
11
+ ---
12
+ # ADR-0069 — A stop gate and a finish tool; the model's checkpoint tool is removed
13
+
14
+ > **Amended by [ADR-0071](ADR-0071-completion-check.md):** `finish` is removed; a completion check (the run's own model, fresh context) now decides `continue` / `needs_person` / `done` when a reply that did work ends with its list closed.
15
+
16
+ ## Context
17
+
18
+ A reply the model ended on its own settled `completed` (`sessions/runner.ts`), and only a
19
+ guard-ended slice auto-continued (`continueSlice`: `terminalReason === 'slice_complete'`). Nothing
20
+ read the todo list when a reply ended.
21
+
22
+ - **Scale.** 207 of 822 runs in the week to 2026-10-30 ended with work left, at a median of 17 tool
23
+ calls; 81 left open todos (`outputs/diagnoses/2026-10-30-sweep.md`).
24
+ - **Worst case.** One terminal session, "Complete platform and API handoff", stopped three times in
25
+ a row with an open todo, at 23, 65 and 94 of 320 tool calls, after being told "dont stop". Its own
26
+ answer in between: "I stopped prematurely… the unfinished work was not all blocked by approval
27
+ gates."
28
+ - **Prompt fixes did not reach it.** ADR-0068's wording was in `src/` but not in `dist/`, and a live
29
+ terminal session keeps the pack and the extension code it started with.
30
+
31
+ **Hypothesis: the harness's own exit ramps make stopping easier.** Several texts made a polished,
32
+ incomplete stop a first-class outcome, with nothing pushing back:
33
+
34
+ - `checkpoint_write`, whose description said to call it "before you stop on purpose";
35
+ - `TODO_GUIDANCE`'s "before your final reply… leave unfinished or blocked steps accurate";
36
+ - ADR-0063's unfinished-handoff guidance;
37
+ - ADR-0068's `## What would make this complete`, "when the run could be more complete".
38
+
39
+ **What the run records show:**
40
+
41
+ - `checkpoint_write` was rarely called: 3 calls in 41 eligible top-level code runs.
42
+ - In run `62c7fc6c` the model wrote a checkpoint on its own ("the handoff remains incomplete…
43
+ continue remaining implementation", nothing `blocked`), made zero further tool calls, and ended.
44
+ It used the checkpoint as a sign-off.
45
+ - Runs that ended with open todos rose from 8% (146 runs before the tool existed) to 42% (19 after).
46
+ The second sample is small and mostly huge handoffs, so this is a signal, not proof. Stopping
47
+ early predates the tool.
48
+
49
+ Other harnesses enforce the end of a turn rather than describe it (STUDY-0004):
50
+
51
+ | Harness | Mechanism |
52
+ |---|---|
53
+ | Claude Code, Codex | `Stop` hook with `decision: block` and a reason |
54
+ | Cursor | `followup_message` with a loop limit |
55
+ | Amp | `agent.end → continue` |
56
+ | Ralph loop | A stop hook with a completion promise and an iteration cap |
57
+ | Gemini CLI | `complete_task` is "the ONLY way to finish" |
58
+ | Cline | `attempt_completion` with a double check |
59
+
60
+ ## Decision
61
+
62
+ 1. **Stop gate.** An extension at Pi's `agent_before_settle` boundary (`sessions/stopGate.ts`) runs
63
+ in every attended top-level run, structured and terminal. It is off in plan, command, automatic,
64
+ subagent and other related runs.
65
+ - When the reply's own `todo_write` list holds an open item and nothing was declared with
66
+ `finish`, it appends a displayed `xingular-stop-gate` message naming the open items and
67
+ continues the same run.
68
+ - It nudges at most three times per reply, and never again after a nudge that produced no tool
69
+ call other than `todo_write` or `finish`.
70
+ - It is silent for a reply with no todo list or a complete one, an aborted or failed reply, a
71
+ slice the guard ended, or a continuation another handler already requested.
72
+ - Each nudge is an `extension.notice` from `stop-gate`.
73
+ - It is deterministic: it reads the todo list and the declaration, never a model judgment.
74
+ 2. **`finish`.** This is the one explicit way to stop with work open (`tools/finish.ts`):
75
+ - `blocked` or `needs_decision` with a reason, plus an optional `needs`;
76
+ - `done` is refused while any item is open;
77
+ - read-only and plan-safe.
78
+ 3. **Honest stop codes.** A reply that settles with open items is `interrupted`, never `completed`:
79
+ - `needs_person` after a `finish` declaration;
80
+ - otherwise `unfinished`.
81
+ The runner (or the terminal extension) writes its checkpoint from evidence: done and next from the
82
+ todo list, blocked from the declaration, files and checks from the reply. Neither auto-continues;
83
+ the person continues the run. (A terminal reply that ended at its work-slice budget, not one of
84
+ these, continues in place since ADR-0070.)
85
+ 4. **No model-written checkpoint.** `checkpoint_write` is removed. At a work-slice budget the guard
86
+ asks the model to stop and report, and the harness writes the checkpoint. A capability set pinned
87
+ before the removal gets `finish` in its place.
88
+ 5. **One budget per reply.** The work-slice guard and the gate reset only on a person's message
89
+ (`before_agent_start` with `messageType: 'user'`). Pi emits `agent_start` for every continuation,
90
+ so resetting there gave every nudge, delivered subagent result or plan repair a fresh 320-call
91
+ budget.
92
+ 6. **Exit ramps rewritten.**
93
+ - `role` names the only reasons to stop, and the gate.
94
+ - `TODO_GUIDANCE` asks for a list that is true at all times.
95
+ - `## What would make this complete` applies only when the work stopped short (blocked, needing
96
+ the person, or handed back by the guard), "never stop early in order to write this section".
97
+ - The `Progress` group explains the gate and `finish`.
98
+ - The terminal's launch tools now include `finish`, so its prompt says so.
99
+ 7. **Subagent tool mismatch is visible.** `spawn_subagent` returns the child's effective `tools`, and
100
+ the read-only profiles say in their first line when a brief needs a tool they lack.
101
+
102
+ ## Consequences
103
+
104
+ - A reply with open todos costs up to three more model requests before it is handed back. A reply
105
+ without a todo list costs nothing extra.
106
+ - A model can still stop with work open, but only by naming a blocker (`needs_person`) or by
107
+ exhausting the gate (`unfinished`). Both are visible in the record and offer Continue.
108
+ - Hosts must accept the two new stop codes (`10-server-protocol.md`). The external App needs a
109
+ release that shows Continue for them.
110
+ - The stable prefix changes once (`role`, `TODO_GUIDANCE`, `reporting`, `Progress`). Measured with
111
+ real requests only, under INV-PRM-8.
112
+ - A live terminal session keeps the code and pack it started with. The gate reaches it only after a
113
+ rebuild and a restart.
114
+ - **Measure:**
115
+ - the share of runs that end with open todos (baseline 81 of 207 `model_behaviour` runs);
116
+ - nudges per run (expected mostly 0–1; more than 3 in a row means the gate's test is wrong);
117
+ - the `unfinished` and `needs_person` rates.
118
+
119
+ ## Alternatives considered
120
+
121
+ - **Widen `continueSlice` to `completed` runs with open todos** (STUDY-0004 option 2). Rejected for
122
+ the first layer: it starts a new run per continuation, needs `continuationOf` to reopen a
123
+ completed run, and does not cover the terminal, where the failing session ran. The gate keeps one
124
+ run and works on both surfaces.
125
+ - **Keep `checkpoint_write` and reword it.** Rejected: any always-available "record where you
126
+ stopped" tool is a sign-off. The harness already derives a better record from evidence.
127
+ - **A model-judged goal evaluator** (Claude Code `/goal`). Rejected, as in STUDY-0004: it adds a
128
+ model call per reply and judges only what the transcript shows.
129
+ - **Prompt only** (ADR-0068 as it stood). Rejected: the record shows the wording does not hold under
130
+ long tasks, and it cannot reach a live session.