@yahyahammad/venastine 0.1.0 → 0.3.8

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 (130) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +249 -93
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +280 -23
  12. package/agents/tui_commands.py +31 -21
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +256 -0
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1249 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +1735 -959
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +2566 -1353
  38. package/core/memory.py +482 -370
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +315 -167
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1672 -198
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +21 -14
  70. package/package.json +303 -73
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +149 -100
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +1082 -682
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +1338 -1005
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +374 -29
  118. package/tui/app.py +5281 -397
  119. package/tui/app.tcss +290 -9
  120. package/tui/commands.py +26 -61
  121. package/tui/diffs.py +286 -265
  122. package/tui/history.py +128 -0
  123. package/tui/hosted_driver.py +102 -0
  124. package/tui/markdown.py +1329 -0
  125. package/tui/meters.py +364 -0
  126. package/tui/screens.py +346 -92
  127. package/tui/themes.py +599 -366
  128. package/tui/widgets.py +2673 -116
  129. package/SECURITY.md +0 -88
  130. package/THIRD_PARTY_NOTICES.md +0 -100
package/main.py CHANGED
@@ -23,17 +23,15 @@ the permanent fallback entry point.
23
23
  import argparse
24
24
  import logging
25
25
  import os
26
+ import signal
26
27
  import sys
28
+ import time
27
29
  from uuid import UUID
28
30
 
29
31
  import config
30
- from core import config_loader, workspace_trust
31
- from core.loop import RunAgentLoop, DEFAULT_PROVIDER
32
- from core.reasoning.authorization import GRANT_PICKER
33
- from core.replay import replay_entries
34
- from database import create_db_and_tables, engine
35
- from logging_setup import configure_logging
36
- from security import posture, protected_paths
32
+ import config_edit
33
+ import config_update
34
+ import core.reasoning.pipeline_storage # noqa: F401 -- registers PipelineRunRecord
37
35
 
38
36
  # Importing these for their SIDE EFFECT, and the side effect is load-bearing:
39
37
  # a SQLModel table class registers on SQLModel.metadata when its module is
@@ -47,11 +45,93 @@ from security import posture, protected_paths
47
45
  # already run, so a FRESH database never got a pipelinerunrecord table and the
48
46
  # first research run died on "no such table". Do not "tidy" these away.
49
47
  import storage # noqa: F401 -- registers ConversationThread, MessageLog
50
- import core.reasoning.pipeline_storage # noqa: F401 -- registers PipelineRunRecord
48
+ from agents.manager import GRILL_ME_TASK
49
+ from cli_commands import (
50
+ ChatSession,
51
+ attach_summary,
52
+ forget_memory,
53
+ print_memories,
54
+ run_command,
55
+ )
56
+ from core import ansi, config_loader, shell_sessions, workspace_trust
57
+ from core.cancel import CancelToken
58
+ from core.loop import (
59
+ DEFAULT_PROVIDER,
60
+ RunAgentLoop,
61
+ advertisement_facts,
62
+ agent_turn,
63
+ )
64
+ from core.reasoning.authorization import GRANT_PICKER
65
+ from core.replay import reasoning_text, replay_entries, step_entries
66
+ from database import create_db_and_tables, engine
67
+ from logging_setup import configure_logging
68
+ from security import posture, protected_paths
51
69
 
52
70
  logger = logging.getLogger(__name__)
53
71
 
54
72
 
73
+ class _Visible:
74
+ """Every untrusted string one prompt prints, and whether any of them
75
+ tried to redraw it (batch 152).
76
+
77
+ THE CLI PRINTS MODEL TEXT TO A TERMINAL, which is the one thing
78
+ `core/ansi.py` exists to make safe, and until this batch only the pty
79
+ and the TUI transcript went through it. The params block was already
80
+ safe -- `_render_params` runs `json.dumps`, which emits an escape as
81
+ `\\u001b` -- and the three lines the user actually decides on were
82
+ plain f-strings. Measured through the real channel: an approval
83
+ headline carrying CSI `2K` reached stdout with the introducer intact,
84
+ and CSI `2K` erases the row the approved command was drawn on.
85
+
86
+ ONE OBJECT PER PROMPT rather than one call per string, because the
87
+ count belongs to the QUESTION and not to any one field: the user is
88
+ told once that something in this call tried to redraw the prompt, not
89
+ once per field that did. `tui/widgets.py` keeps the same count for the
90
+ same reason and `tui/app.py` reads it, which is the layer that knows
91
+ whose text it was; here that layer is the handler.
92
+
93
+ SAID OUT LOUD, not swallowed. A silent strip leaves the display honest
94
+ and the user ignorant of the attempt, and the attempt is information
95
+ they are entitled to while deciding -- nothing a tool legitimately
96
+ needs to do involves moving the cursor inside a consent prompt. On the
97
+ paths where nothing is being decided (a replayed thread, a research
98
+ pass's progress lines) the strip is silent, because there is no
99
+ decision for the warning to inform.
100
+ """
101
+
102
+ def __init__(self, reveal: bool = False) -> None:
103
+ self.controls = 0
104
+ # AN APPROVAL ALSO REVEALS what draws text out of order or not at
105
+ # all -- bidi overrides, zero-width and tag characters -- as
106
+ # `<U+202E>` (TECHNICAL_DEBT 104, batch 160). Only an approval, by
107
+ # owner ruling: elsewhere those characters are somebody's Arabic,
108
+ # Persian or emoji, and `core/ansi.reveal_invisible_counted` says
109
+ # why the trade reverses where a person is authorising a command.
110
+ self._reveal = reveal
111
+ self.revealed = 0
112
+
113
+ def __call__(self, text) -> str:
114
+ clean, removed = ansi.for_display_counted(text)
115
+ self.controls += removed
116
+ if self._reveal:
117
+ clean, shown = ansi.reveal_invisible_counted(clean)
118
+ self.revealed += shown
119
+ return clean
120
+
121
+ def warn(self) -> None:
122
+ """One line per kind, immediately above the question, or nothing."""
123
+ if self.controls:
124
+ plural = "" if self.controls == 1 else "s"
125
+ print(f" [!] {self.controls} terminal control sequence{plural} "
126
+ f"removed from the text above: something in this call "
127
+ f"tried to redraw this prompt")
128
+ if self.revealed:
129
+ plural = "" if self.revealed == 1 else "s"
130
+ print(f" [!] {self.revealed} invisible or reordering "
131
+ f"character{plural} shown as <U+...> in the text above: "
132
+ f"read it as written, not as drawn")
133
+
134
+
55
135
  def _uuid_type(value: str) -> UUID:
56
136
  """Argparse type validator for --thread. Produces a clear CLI error
57
137
  for a malformed UUID instead of a traceback from deep in storage."""
@@ -83,25 +163,203 @@ def _print_replay(thread_id: UUID) -> None:
83
163
  except Exception as e: # noqa: BLE001 -- a display failure must not
84
164
  # stop the session: the thread is loaded and usable either way.
85
165
  logger.warning("Could not replay thread %s: %s", thread_id, e)
86
- print(f"[could not replay this thread's history: {e}]")
166
+ print("[could not replay this thread's history: "
167
+ f"{ansi.for_display(e)}]")
87
168
  return
88
169
  if not entries:
89
170
  print("(this thread has no messages yet)")
90
171
  return
91
172
  print()
92
- for role, text in entries:
93
- if role == "user":
94
- print(f"You: {text}")
95
- elif role == "assistant":
96
- print(f"\nAgent: {text}\n")
97
- elif role == "thinking":
98
- print(f"\nThinking: {text}")
99
- else:
100
- print(f" {text}")
173
+ # `links` is the TUI's -- a ctrl+click target for a truncated URL
174
+ # (batch 65) -- and `_call` is §47's, the id of the spawn that made
175
+ # this line, which the TUI turns into an openable run. This shell
176
+ # prints, so it drops both.
177
+ # Every row here is text somebody else wrote -- the model, a tool,
178
+ # or a wake the harness composed around a tool's result -- replayed
179
+ # into a terminal, which is `core/ansi.for_display`'s whole subject
180
+ # (batch 152). Silent, because a replay decides nothing.
181
+ for role, text, _links, _call in entries:
182
+ _print_entry(role, text)
101
183
  noun = "entry" if len(entries) == 1 else "entries"
102
184
  print(f"--- end of {len(entries)} replayed {noun} ---")
103
185
 
104
186
 
187
+ def _print_entry(role: str, text: str) -> None:
188
+ """One display entry, labelled the way this shell labels it.
189
+
190
+ Shared by a replay and a live turn (ROADMAP_v3 §86, A81), so the two
191
+ cannot come to label one entry two ways.
192
+ """
193
+ text = ansi.for_display(text)
194
+ if role == "user":
195
+ print(f"You: {text}")
196
+ elif role == "assistant":
197
+ print(f"\nAgent: {text}\n")
198
+ elif role == "thinking":
199
+ print(f"\nThinking: {text}")
200
+ elif role == "wake":
201
+ # ROADMAP_v3 §49 (SS5): written by the harness, not the person,
202
+ # so it does not take the "You:" label the TUI also withholds.
203
+ print(f"Harness: {text}")
204
+ else:
205
+ print(f" {text}")
206
+
207
+
208
+ class _LiveTurn:
209
+ """Prints a chat or wake turn while it runs, one model step at a time
210
+ (ROADMAP_v3 §86, A81; #225).
211
+
212
+ Before this the CLI drained a turn and printed its notices and its
213
+ final answer, while a replay of the same thread showed the reasoning
214
+ and a line per tool call. One run looked different depending on
215
+ whether its thread had been closed, which is what `core/replay.py`
216
+ exists to prevent.
217
+
218
+ A STEP IS PRINTED WHEN IT FINISHES, never while it streams: at its
219
+ first tool call, or at `finish` for the last one. The loop announces a
220
+ step's tool calls only after the step is complete and saved, and a
221
+ `retract` arrives only while it streams, so this printer never has to
222
+ take anything back. It drops what it was holding. And no answer is
223
+ printed in pieces, so the line a Ctrl+C prints never lands inside one.
224
+
225
+ WHAT a step prints is `core.replay.step_entries`, the replay's own
226
+ function. The one difference is where an intermediate step's text
227
+ comes from: the event that ends it carries no response, so its
228
+ reasoning and text are what streamed. The last step is read from the
229
+ response itself, so the answer never depends on a provider having
230
+ streamed it.
231
+
232
+ Notices print when they arrive, which is when they happened. The ones
233
+ a response also carries print at `finish` only if they never arrived
234
+ live, so each prints once. That includes `todo_write`'s one-line
235
+ summary, whose docstring says it is "for the CLI, which has no panel".
236
+ The CLI could not show it until now, because it drained the event
237
+ that carries it.
238
+ """
239
+
240
+ def __init__(self):
241
+ self._reasoning: list[str] = []
242
+ self._text: list[str] = []
243
+ self._announced: set = set()
244
+ # The notices themselves rather than their ids: a tool's notice
245
+ # is popped out of its result and referenced by nothing else, so
246
+ # its id could be reused by a later one.
247
+ self._noticed: list = []
248
+
249
+ def __call__(self, event) -> None:
250
+ try:
251
+ self._draw(event)
252
+ except Exception: # noqa: BLE001 -- display must not end a turn
253
+ # An exception here would propagate out of the generator the
254
+ # loop is running, abandoning the turn over a print.
255
+ logger.exception("Could not print a live turn event")
256
+
257
+ def _draw(self, event) -> None:
258
+ if event.retract:
259
+ self._reasoning.clear()
260
+ self._text.clear()
261
+ elif event.thinking_delta:
262
+ self._reasoning.append(event.thinking_delta)
263
+ elif event.token_delta:
264
+ self._text.append(event.token_delta)
265
+ elif event.notice:
266
+ self._notice(event.notice)
267
+ elif event.tool_call_start:
268
+ call = event.tool_call_start
269
+ self._announced.add(call.get("id"))
270
+ self._step("".join(self._reasoning).strip(),
271
+ "".join(self._text), [call])
272
+
273
+ def _step(self, reasoning: str, text: str, calls) -> None:
274
+ self._reasoning.clear()
275
+ self._text.clear()
276
+ for role, line, _links, _opens in step_entries(reasoning, text,
277
+ calls):
278
+ _print_entry(role, line)
279
+
280
+ def _notice(self, notice) -> None:
281
+ if any(notice is seen for seen in self._noticed):
282
+ return
283
+ self._noticed.append(notice)
284
+ text = notice.get("text") if isinstance(notice, dict) else None
285
+ if text:
286
+ print(f"— {ansi.for_display(text)} —")
287
+
288
+ def finish(self, response) -> None:
289
+ """The turn's last step, from the response the turn returned.
290
+
291
+ Called by the shell rather than by the loop's terminal event, so a
292
+ turn that was never observed still prints its answer.
293
+ """
294
+ for notice in getattr(response, "notices", ()):
295
+ self._notice(notice)
296
+ calls = [{"id": c.id, "name": c.name, "input": c.input}
297
+ for c in getattr(response, "tool_calls", None) or ()]
298
+ if any(c["id"] in self._announced for c in calls):
299
+ # This step's reasoning and text printed with its first tool
300
+ # line: the turn ran out of steps or was stopped between its
301
+ # tool calls, after the step itself had finished.
302
+ reasoning, text = "", ""
303
+ else:
304
+ reasoning = reasoning_text(getattr(response, "thinking", None))
305
+ text = response.text
306
+ self._step(reasoning, text,
307
+ [c for c in calls if c["id"] not in self._announced])
308
+
309
+
310
+ TURN_STOP_CONFIRM_S = 2.0
311
+ """How long the first Ctrl+C during a turn waits for a second (§86, A81).
312
+
313
+ The TUI's `QUIT_CONFIRM_S`, and held equal to it by a test: one gesture,
314
+ one window, in both shells. Not imported from there because `tui.app`
315
+ imports Textual, which a CLI run never otherwise loads."""
316
+
317
+
318
+ class _SecondPress:
319
+ """A SIGINT handler that acts on the SECOND press inside the window
320
+ (ROADMAP_v3 §86, A81; #244).
321
+
322
+ The first press changes nothing and says what a second would do. A
323
+ second within `TURN_STOP_CONFIRM_S` acts, once, and every press after
324
+ that is ignored. A press after the window closes arms it again. This
325
+ is the TUI's two-press quit, without its copy check, which the CLI
326
+ cannot port because the selection belongs to the terminal.
327
+
328
+ It exists because CN10 made the FIRST press stop the turn, and a press
329
+ aimed at copying, or a stray one, cost a model turn. A21 refused one
330
+ press in the session wait for that reason. Here the same rule covers
331
+ both places a turn runs, the user's own and a wake.
332
+
333
+ `__name__` is set because a signal handler is usually a function, and
334
+ whoever inspects `signal.getsignal` should still see which one is
335
+ installed.
336
+ """
337
+
338
+ def __init__(self, name: str, armed: str, act):
339
+ self.__name__ = name
340
+ self._armed = armed
341
+ self._act = act
342
+ self._armed_at = None
343
+ self._acted = False
344
+
345
+ def __call__(self, _signum, _frame) -> None:
346
+ if self._acted:
347
+ return
348
+ now = time.monotonic()
349
+ if (self._armed_at is not None
350
+ and now - self._armed_at <= TURN_STOP_CONFIRM_S):
351
+ self._acted = True
352
+ self._act()
353
+ return
354
+ self._armed_at = now
355
+ print(f"\n[{self._armed}]", flush=True)
356
+
357
+
358
+ def _again_within() -> str:
359
+ """'Ctrl+C again within 2s', from the constant rather than a copy."""
360
+ return f"Ctrl+C again within {TURN_STOP_CONFIRM_S:g}s"
361
+
362
+
105
363
 
106
364
  def _announce_posture() -> None:
107
365
  """Say, at every launch, which shipped protections are off (§40 UN3).
@@ -130,6 +388,212 @@ def _announce_posture() -> None:
130
388
  print("", file=sys.stderr)
131
389
 
132
390
 
391
+ # ROADMAP_v3 §49 (SS2, SS5, SS6, SS19). The CLI's half of background
392
+ # sessions. D12 keeps this shell a permanent fallback, so waiting on a
393
+ # session, running the turn its result starts, stopping one and confirming
394
+ # a quit all have to work here and not only in the TUI -- a session the CLI
395
+ # could start and never report would be exactly the wired-up-but-invisible
396
+ # gap D12 exists to prevent.
397
+ sessions = shell_sessions.sessions
398
+ """The process's one session manager, bound once at import.
399
+
400
+ A module-level name rather than a lookup per call, because in production it
401
+ is a singleton that never changes. The consequence, named rather than
402
+ discovered: a test that replaces the manager has to patch THIS name as well
403
+ as `core.shell_sessions.sessions`.
404
+ """
405
+
406
+
407
+ def _quit_confirmed() -> bool:
408
+ """SS6: quitting with sessions still running confirms first.
409
+
410
+ They are killed on the way out and their output is not kept, so leaving
411
+ is a decision rather than a default. NOBODY TO ASK COUNTS AS YES --
412
+ Ctrl+D, a piped run, a closed terminal -- because a harness that cannot
413
+ be exited is the worse failure, and `ask` returns None on exactly those.
414
+ """
415
+ live = len(sessions.live_rows())
416
+ if not live:
417
+ return True
418
+ answer = _stdin_reader().ask(
419
+ f"{live} background session(s) are still running and will be "
420
+ f"stopped. Quit? [y/N]: ")
421
+ return answer is None or answer.strip().lower().startswith("y")
422
+
423
+
424
+ def _deliver_held(thread_id) -> None:
425
+ """Results held for the user's next message (SS2, SS19).
426
+
427
+ Written into the thread as a harness row BEFORE the turn that answers
428
+ the message, so the model reads them beside what the user just typed
429
+ rather than as a turn of their own -- which is the whole point of
430
+ holding them: a kill the user made is not worth a model call on its own.
431
+ """
432
+ from core.memory import append_harness_row
433
+ from core.session_wake import build_held
434
+
435
+ held = sessions.take_held(thread_id)
436
+ if not held:
437
+ return
438
+ text, record = build_held(held)
439
+ append_harness_row(thread_id, text, record)
440
+ print(f"— {ansi.for_display(text.splitlines()[0])} —")
441
+
442
+
443
+ def _await_sessions(thread_id, *, model, provider_name, effort,
444
+ authorization, turn=None, active_skills=()) -> None:
445
+ """Between turns, wait on this conversation's live sessions and run a
446
+ wake turn for each batch (SS2, SS5).
447
+
448
+ Ctrl+C here stops the SESSIONS and returns to the prompt: the interrupt
449
+ is aimed at what is running, not at the conversation. Their results are
450
+ then held for the next message (SS19), so nothing is printed about them
451
+ beyond the count.
452
+
453
+ THAT SENTENCE OUTLIVED ITS PREMISE, and ROADMAP_v3 §64's A21 is the
454
+ answer. Once SS5 made a wake a full model TURN with tool dispatch, "what
455
+ is running" during one IS the conversation -- `wake_conversation`'s own
456
+ docstring says "it IS that run continuing" -- and the per-turn SIGINT
457
+ handler CN10 installs is restored in `run_chat`'s `finally` before this
458
+ function is ever called. So the default handler was live here, and a
459
+ Ctrl+C during a wake raised `KeyboardInterrupt` from wherever it landed:
460
+ `_run`'s frame catches `Exception`, not `BaseException`, so it passed
461
+ straight through, and if it landed between the `tool_use` D20 has
462
+ already persisted and the `tool_result` that pairs with it, the thread
463
+ was left unresumable -- the very damage CN10 exists to prevent, in the
464
+ one place CN10 did not reach.
465
+
466
+ THE KEY STILL MEANS WHAT THE BANNER SAYS. It is not bound to stopping
467
+ the turn, deliberately: a press aimed at copying or pasting must not be
468
+ able to end a model turn, which is the measurement behind the TUI's
469
+ batch-57 rule ("ctrl+c copies when there is something to copy, and
470
+ starts a quit when there is not"). What changed is only the mechanism --
471
+ for the duration of each wake turn a handler of this function's own
472
+ DEFERS the interrupt: the sessions stop once the turn has finished and
473
+ written the rows it owes, which is CN10's own "the current step finishes
474
+ first" pointed at the sessions instead of the turn. Since ROADMAP_v3
475
+ §86 (A81) that handler acts only on a second press inside
476
+ `TURN_STOP_CONFIRM_S`, as the user's own turn does, and a wake turn
477
+ prints its steps live as the user's own turn does.
478
+
479
+ The wake turn carries the run's own `authorization`, because it is that
480
+ run continuing -- without it every gated call inside a wake would be
481
+ denied for a reason about the harness rather than the request. For the
482
+ same reason it carries the turn's agent (`turn`, `core.loop.AgentTurn`)
483
+ and the session's active skills (ROADMAP_v3 §89): a wake under a
484
+ different prompt from the turn it continues is a different agent
485
+ answering.
486
+ """
487
+ from core.session_wake import build_wake
488
+
489
+ if thread_id is None:
490
+ return
491
+ as_agent = ({} if turn is None else {
492
+ "context": turn.context, "system_prompt": turn.system_prompt,
493
+ "max_steps": turn.max_steps})
494
+ announced = False
495
+ # §64 A21. Set by the handler below instead of an unwind; read after the
496
+ # wake turn has finished. A list rather than a `nonlocal` because the
497
+ # handler is a closure over this frame either way and a one-element list
498
+ # cannot be rebound by accident.
499
+ interrupted = []
500
+
501
+ def _stop_sessions_after_this_turn():
502
+ # Installed only while a wake turn runs, and restored in a
503
+ # `finally`, so Ctrl+C while merely WAITING still takes the
504
+ # `except KeyboardInterrupt` below -- there is no turn to protect
505
+ # there, and nothing to defer for. `signal.signal` is main-thread
506
+ # only, which is where the CLI's chat loop and therefore this runs.
507
+ #
508
+ # §86 (A81): the SECOND press inside the window, so a stray one
509
+ # during a wake turn costs nothing, as it costs nothing during the
510
+ # user's own.
511
+ interrupted.append(True)
512
+ print("\n[stopping the background sessions - this turn "
513
+ "finishes first]", flush=True)
514
+
515
+ try:
516
+ while True:
517
+ live = sessions.live_for(thread_id)
518
+ if not live and not sessions.pending(thread_id):
519
+ return
520
+ if not announced:
521
+ print(f"[waiting on {live} background session(s) — "
522
+ f"Ctrl+C stops them]")
523
+ announced = True
524
+ batch = sessions.wait_for_wake(thread_id, timeout=1.0)
525
+ if batch is None:
526
+ if sessions.suspended(thread_id):
527
+ print("[no further automatic replies until you say "
528
+ "something — results will arrive with your next "
529
+ "message]")
530
+ return
531
+ continue
532
+ text, record = build_wake(batch)
533
+ previous_sigint = signal.signal(signal.SIGINT, _SecondPress(
534
+ "_stop_sessions_after_this_turn",
535
+ f"{_again_within()} stops the background sessions once "
536
+ f"this turn finishes",
537
+ _stop_sessions_after_this_turn))
538
+ live = _LiveTurn()
539
+ try:
540
+ # A wake turn may start sessions of its own, and something
541
+ # is still here to report them: this loop.
542
+ with shell_sessions.consuming():
543
+ response = RunAgentLoop.wake_conversation(
544
+ thread_id=thread_id, text=text, harness=record,
545
+ model=model, provider_name=provider_name,
546
+ effort=effort, authorization=authorization,
547
+ observe=live, active_skills=active_skills,
548
+ **as_agent)
549
+ except Exception as e:
550
+ logger.exception("Wake turn failed")
551
+ print(f"\n[Error: {ansi.for_display(e)}]")
552
+ return
553
+ finally:
554
+ # Before anything else can be printed or read, and on the
555
+ # error path too: outside a wake turn the interrupt belongs
556
+ # to the sessions and takes the handler below.
557
+ signal.signal(signal.SIGINT, previous_sigint)
558
+ live.finish(response)
559
+ if interrupted:
560
+ # The turn finished and wrote its rows; now the key does
561
+ # what it said. Returning to the prompt rather than waiting
562
+ # on the next batch, because the press was a request to
563
+ # stop waiting -- SS19 holds whatever arrives after this
564
+ # for the next message either way.
565
+ killed = sessions.kill_owned(thread_id,
566
+ shell_sessions.KILL_USER)
567
+ print(f"\n[stopped {len(killed)} background session(s)]")
568
+ return
569
+ except KeyboardInterrupt:
570
+ killed = sessions.kill_owned(thread_id, shell_sessions.KILL_USER)
571
+ print(f"\n[stopped {len(killed)} background session(s)]")
572
+
573
+
574
+ def _close_sessions() -> None:
575
+ """Kill every live session on the way out and record what became of
576
+ them (SS6), then sweep any container this process left behind.
577
+
578
+ Contained on both halves: this runs while the process is already
579
+ leaving, and a failure to tidy up must not replace whatever the user
580
+ was actually told.
581
+ """
582
+ from core.session_wake import record_killed_at_quit
583
+ from security.sandbox import kill_labelled_containers
584
+
585
+ try:
586
+ closed = sessions.close()
587
+ if closed:
588
+ record_killed_at_quit(closed)
589
+ except Exception: # noqa: BLE001 -- on the way out
590
+ logger.exception("Could not close background sessions cleanly")
591
+ try:
592
+ kill_labelled_containers()
593
+ except Exception: # noqa: BLE001 -- on the way out
594
+ logger.exception("Could not clean up this process's containers")
595
+
596
+
133
597
  def run_chat(
134
598
  thread_id: UUID | None,
135
599
  provider_name: str,
@@ -144,30 +608,56 @@ def run_chat(
144
608
  Batch 25 (#139): `effort` is the resolved level (resolve_effort). It
145
609
  rides every run_agent_conversation call and is printed in the header,
146
610
  because a setting that shapes every answer should be visible where the
147
- provider and model are."""
148
- current_thread_id = thread_id
149
- printed_thread_id = False
150
- # §21b M16. Built once for the session rather than per turn: the
151
- # provider wraps the single _stdin_reader, and building one per turn
152
- # would be a new object round the same reader for no gain. None on a
153
- # non-tty, which keeps a piped run headless exactly as before.
154
- authorization = build_chat_authorization()
611
+ provider and model are.
612
+
613
+ ROADMAP_v3 §89 (#8): a line starting with `/` is a COMMAND, run by
614
+ `cli_commands.run_command` against the catalog both shells bind to,
615
+ and never sent to the model -- the TUI's rule since §16. What the
616
+ commands can change between turns (the thread, the model, the effort,
617
+ the active agent and skills) is held on one `ChatSession`, which every
618
+ turn reads."""
619
+ session = ChatSession(
620
+ provider_name, model, effort=effort, thread_id=thread_id,
621
+ # §21b M16. Built once for the session rather than per turn: the
622
+ # provider wraps the single _stdin_reader, and building one per
623
+ # turn would be a new object round the same reader for no gain.
624
+ # None on a non-tty, which keeps a piped run headless exactly as
625
+ # before.
626
+ authorization=build_chat_authorization(),
627
+ # What cli_commands needs from this module, handed over rather
628
+ # than imported: this file runs as __main__ (see its docstring).
629
+ ask=lambda prompt: _stdin_reader().readline(prompt),
630
+ replay=_print_replay, show=_print_entry)
155
631
 
156
632
  print("Venastine Research Harness — chat mode.")
157
633
  print(f"Provider: {provider_name} | Model: {model} | "
158
634
  f"Effort: {effort or 'auto'}")
159
- if current_thread_id:
160
- print(f"Resuming thread: {current_thread_id}")
635
+ # ROADMAP_v3 §57 (SM10). A remembered submodel puts this shell's spawned
636
+ # subagents on a model no flag or config file names, so it is said
637
+ # where the session's own pair is.
638
+ from core import connect
639
+
640
+ submodel = connect.submodel_label()
641
+ if submodel:
642
+ print(f"Subagents: {submodel} (remembered; /submodel off clears it)")
643
+ if session.thread_id:
644
+ print(f"Resuming thread: {session.thread_id}")
161
645
  # §27 AC4/T5. --thread had the same gap as the TUI picker: the
162
646
  # history loaded and nothing showed it, so a resumed conversation
163
647
  # was indistinguishable from a new one until the model answered
164
648
  # with context the user could not see. D12 makes the CLI a
165
649
  # permanent fallback, so it replays too rather than this being a
166
650
  # TUI feature.
167
- _print_replay(current_thread_id)
651
+ _print_replay(session.thread_id)
168
652
  else:
169
653
  print("Starting a new conversation thread.")
170
- print("Ctrl+C or Ctrl+D to exit.\n")
654
+ # ROADMAP_v3 §61 (CN10). The key did only one thing before and now
655
+ # does two, so the banner says which is which. A control whose
656
+ # meaning depends on state and does not announce it is the thing
657
+ # this project keeps closing. "Twice" since §86 (A81), and the
658
+ # commands named since §89, which is how a reader learns they exist.
659
+ print("Ctrl+C twice stops the current turn; Ctrl+C or Ctrl+D at the "
660
+ "prompt exits. /help lists commands.\n")
171
661
 
172
662
  while True:
173
663
  if first_message is not None:
@@ -182,59 +672,185 @@ def run_chat(
182
672
  # readline() raises it on Ctrl+D exactly as input() did.
183
673
  user_input = _stdin_reader().readline("You: ").strip()
184
674
  except (KeyboardInterrupt, EOFError):
675
+ # ROADMAP_v3 §49 (SS6). Quitting with sessions still
676
+ # running confirms first -- they are killed on the way out
677
+ # and their output is not kept, so leaving is a decision.
678
+ # Nobody to ask (Ctrl+D, a piped run) counts as yes: a
679
+ # harness that cannot be exited is the worse failure.
680
+ if not _quit_confirmed():
681
+ continue
185
682
  print("\nExiting.")
186
683
  break
187
684
 
188
685
  if not user_input:
189
686
  continue
190
687
 
191
- try:
688
+ agent = session.active_agent
689
+ one_shot = False
690
+ if user_input.startswith("/"):
691
+ run_command(session, user_input)
692
+ if session.quit_requested:
693
+ # /quit takes Ctrl+D's route, confirmation and all.
694
+ session.quit_requested = False
695
+ if _quit_confirmed():
696
+ print("Exiting.")
697
+ break
698
+ continue
699
+ if session.one_shot is None:
700
+ continue
701
+ # /grill-me: one turn in this thread under that agent's prompt,
702
+ # run like a typed message so it prints live and stops the same
703
+ # way (§18; the TUI's run_one_shot).
704
+ agent, session.one_shot = session.one_shot, None
705
+ user_input, one_shot = GRILL_ME_TASK, True
706
+
707
+ _chat_turn(session, user_input, agent, one_shot=one_shot)
708
+
709
+
710
+ def _chat_turn(session: ChatSession, user_input: str, agent,
711
+ one_shot: bool = False) -> None:
712
+ """One turn of `run_chat`'s conversation, and the wake turns after it.
713
+
714
+ `agent` is the session's active agent, or /grill-me's for its one turn
715
+ (`one_shot`). What the agent changes about the turn is
716
+ `core.loop.agent_turn`'s to say, the function the TUI's turn calls, so
717
+ an agent is the same agent in either shell (§89).
718
+ """
719
+ if session.thread_id is not None:
720
+ # SS2/SS19: what was held because nothing was waking this
721
+ # conversation arrives WITH the user's next message, in the
722
+ # same thread, before the turn that answers them both.
723
+ _deliver_held(session.thread_id)
724
+ sessions.note_user_input(session.thread_id)
725
+
726
+ # #68's facts, for an agent's prompt only: with no agent the loop
727
+ # builds the default prompt and reads them itself.
728
+ callable_only, granted = (advertisement_facts(session.authorization)
729
+ if agent is not None else (False, None))
730
+ turn = agent_turn(agent, session.model, session.provider_name,
731
+ session.active_skills, callable_only=callable_only,
732
+ granted=granted, one_shot=one_shot)
733
+
734
+ # ROADMAP_v3 §61 (CN10). A HANDLER rather than an `except
735
+ # KeyboardInterrupt`, and the difference is what the thread
736
+ # looks like afterwards. An interrupt unwinds from wherever it
737
+ # lands -- which can be between a `tool_use` D20 has persisted
738
+ # and the `tool_result` that pairs with it, leaving a thread the
739
+ # provider will refuse to continue (#42, M4). The token lets the
740
+ # loop stop at a boundary it chose and write every row it owes.
741
+ #
742
+ # Installed per turn and restored in the `finally`, so Ctrl+C at
743
+ # the prompt still exits and Ctrl+C during the session wait
744
+ # still stops the SESSIONS.
745
+ #
746
+ # The aim of the key there was always right; the MECHANISM was
747
+ # not, and batch 147 fixed that end rather than this one. Because
748
+ # this handler is restored before `_await_sessions` is called, a
749
+ # Ctrl+C during a WAKE turn met the default handler and unwound
750
+ # the turn from wherever it landed -- so `_await_sessions` now
751
+ # installs a handler of its own for the duration of each wake,
752
+ # which defers the interrupt instead of raising it. See §64 A21.
753
+ #
754
+ # `signal.signal` is main-thread only, which is where this runs.
755
+ # Since §86 the turn prints while it runs, but a step at a time and
756
+ # only once it has finished, so the line below lands between
757
+ # printed steps and never inside a streaming answer.
758
+ #
759
+ # §86 (A81, #244): the SECOND press inside TURN_STOP_CONFIRM_S. CN10
760
+ # made the first press stop the turn, and a stray press or one
761
+ # aimed at copying cost a model turn -- A21's reason, applied to
762
+ # the binding A21 left alone.
763
+ cancel = CancelToken()
764
+
765
+ def _stop_this_turn(_token=cancel):
766
+ if _token.cancel():
767
+ print("\n[stopping — the current step finishes first]",
768
+ flush=True)
769
+
770
+ previous_sigint = signal.signal(signal.SIGINT, _SecondPress(
771
+ "_stop_this_turn", f"{_again_within()} stops this turn",
772
+ _stop_this_turn))
773
+ live = _LiveTurn()
774
+ try:
775
+ # SS17. The CLI chat turn is a wake consumer: a session started
776
+ # here is reported by the loop below, which is what makes
777
+ # starting one allowed at all.
778
+ with shell_sessions.consuming():
192
779
  response = RunAgentLoop.run_agent_conversation(
193
780
  user_goal=user_input,
194
- model=model,
195
- provider_name=provider_name,
196
- thread_id=current_thread_id,
197
- authorization=authorization,
198
- effort=effort,
781
+ model=turn.model,
782
+ provider_name=turn.provider_name,
783
+ max_steps=turn.max_steps,
784
+ thread_id=session.thread_id,
785
+ context=turn.context,
786
+ system_prompt=turn.system_prompt,
787
+ active_skills=session.active_skills,
788
+ authorization=session.authorization,
789
+ effort=session.effort,
790
+ cancel=cancel,
791
+ observe=live,
199
792
  )
200
- except Exception as e:
201
- logger.exception("Chat turn failed")
202
- print(f"\n[Error: {e}]")
203
- continue
204
-
205
- current_thread_id = response.thread_id
206
-
207
- if not printed_thread_id and current_thread_id:
208
- print(f"[thread: {current_thread_id}]")
209
- printed_thread_id = True
210
-
211
- # ROADMAP_v2 §21's "no silent compaction, ever". The CLI drains
212
- # the generator through run_to_completion(), which discards every
213
- # non-final event -- so these arrive on the response rather than as
214
- # LoopEvents. Printed BEFORE the answer, because that is when they
215
- # happened.
216
- for notice in getattr(response, "notices", ()):
217
- print(f"— {notice['text']} —")
218
-
219
- print(f"\nAgent: {response.text}")
220
- if response.stop_reason != "complete":
221
- # #4: name the figures, not just the reason. A user who sees
222
- # "token_budget_exceeded" reads it as a size problem -- the
223
- # exact misreading item 9 recorded -- so the line now says
224
- # what actually happened (spend this turn) alongside the
225
- # thread's real size (the provider's own last count). Rare
226
- # path, so a storage read for the ctx figure costs nothing.
227
- billed = getattr(response, "turn_billed_tokens", None)
228
- ctx = 0
229
- if current_thread_id:
230
- row = storage.get_thread(current_thread_id) or {}
231
- ctx = int((row.get("extra_data") or {}).get(
232
- "last_input_tokens") or 0)
233
- figures = f" — billed {billed:,} this turn · ctx ~{ctx:,}" \
234
- if billed is not None else ""
235
- print(f"[stopped early: {response.stop_reason}{figures}]")
793
+ except Exception as e:
794
+ logger.exception("Chat turn failed")
795
+ print(f"\n[Error: {ansi.for_display(e)}]")
796
+ return
797
+ finally:
798
+ signal.signal(signal.SIGINT, previous_sigint)
799
+
800
+ session.thread_id = response.thread_id
801
+
802
+ # ROADMAP_v2 §21's "no silent compaction, ever": a notice printed
803
+ # live when it happened, and one that never arrived live is printed
804
+ # here, before the answer. §86 (A81): the turn's last step, the
805
+ # answer included, read from the response it returned.
806
+ live.finish(response)
807
+ trailer = False
808
+ if response.stop_reason != "complete":
809
+ # #4: name the figures, not just the reason. A user who sees
810
+ # "token_budget_exceeded" reads it as a size problem -- the
811
+ # exact misreading item 9 recorded -- so the line now says
812
+ # what actually happened (spend this turn) alongside the
813
+ # thread's real size (the provider's own last count). Rare
814
+ # path, so a storage read for the ctx figure costs nothing.
815
+ billed = getattr(response, "turn_billed_tokens", None)
816
+ ctx = 0
817
+ if session.thread_id:
818
+ row = storage.get_thread(session.thread_id) or {}
819
+ ctx = int((row.get("extra_data") or {}).get(
820
+ "last_input_tokens") or 0)
821
+ figures = f" — billed {billed:,} this turn · ctx ~{ctx:,}" \
822
+ if billed is not None else ""
823
+ # ROADMAP_v3 §61 (CN5). An empty usage dict means the loop
824
+ # synthesised this response because the stream was cut, so
825
+ # the step that was interrupted reported no usage at all and
826
+ # `billed` is short by it. Stated, because a figure that is
827
+ # quietly incomplete is worse than one that admits it.
828
+ if response.stop_reason == "cancelled" and not response.usage:
829
+ figures += " (the stopped step is not counted)"
830
+ print(f"[stopped early: {ansi.for_display(response.stop_reason)}"
831
+ f"{figures}]")
832
+ trailer = True
833
+ # After the answer rather than above it, since §86: above, it
834
+ # would split a turn's printed steps from its last one.
835
+ if not session.printed_thread_id and session.thread_id:
836
+ print(f"[thread: {session.thread_id}]")
837
+ session.printed_thread_id = True
838
+ trailer = True
839
+ if trailer:
840
+ # The answer's own line ends in a blank one; a trailer gets
841
+ # one of its own before the prompt.
236
842
  print()
237
843
 
844
+ # SS2/SS5. The turn is over, but this conversation may not be: a
845
+ # session it started reports later, and that report starts a turn
846
+ # of its own -- under the same agent, prompt and skills, because it
847
+ # IS this turn continuing. Nothing is read from the user until they
848
+ # are done.
849
+ _await_sessions(session.thread_id, model=turn.model,
850
+ provider_name=turn.provider_name, effort=session.effort,
851
+ authorization=session.authorization, turn=turn,
852
+ active_skills=session.active_skills)
853
+
238
854
 
239
855
  def build_research_authorization(grant_spec, attended: bool = False):
240
856
  """Turn --grant/--grant-tools/--attended into a RunAuthorization.
@@ -251,7 +867,10 @@ def build_research_authorization(grant_spec, attended: bool = False):
251
867
  """
252
868
  from core.approval import GrantBudget, RunAuthorization
253
869
  from core.reasoning.authorization import (
254
- NOTHING_TO_GRANT, candidates, parse_grant_spec, GrantSpecError,
870
+ NOTHING_TO_GRANT,
871
+ GrantSpecError,
872
+ candidates,
873
+ parse_grant_spec,
255
874
  )
256
875
 
257
876
  if grant_spec is None and not attended:
@@ -284,7 +903,7 @@ def build_research_authorization(grant_spec, attended: bool = False):
284
903
  "picker; pass the names explicitly to grant them in a "
285
904
  "script. Skipping:", file=sys.stderr)
286
905
  for name, description in offered:
287
- print(f" - {name}", file=sys.stderr)
906
+ print(f" - {ansi.for_display(name)}", file=sys.stderr)
288
907
  return _attended_only(provider)
289
908
  granted = _pick_tools_to_grant(offered)
290
909
  else:
@@ -341,6 +960,54 @@ def _attended_only(provider):
341
960
  _DEFAULT_TIMEOUT = object()
342
961
 
343
962
 
963
+ def _flush_console_input(handle) -> None:
964
+ """Windows: empty a console's input buffer, then clear the edit line of
965
+ a cooked read in progress with one Escape key (ROADMAP_v3 §88, A83).
966
+
967
+ `_StdinReader._flush_terminal` says why both halves are needed. The
968
+ structures are declared here, on first use, because only a Windows
969
+ console ever reaches this.
970
+ """
971
+ import ctypes
972
+ from ctypes import wintypes
973
+
974
+ class _Char(ctypes.Union):
975
+ _fields_ = [("UnicodeChar", wintypes.WCHAR),
976
+ ("AsciiChar", ctypes.c_char)]
977
+
978
+ class _KeyEvent(ctypes.Structure):
979
+ _fields_ = [("bKeyDown", wintypes.BOOL),
980
+ ("wRepeatCount", wintypes.WORD),
981
+ ("wVirtualKeyCode", wintypes.WORD),
982
+ ("wVirtualScanCode", wintypes.WORD),
983
+ ("uChar", _Char),
984
+ ("dwControlKeyState", wintypes.DWORD)]
985
+
986
+ class _Event(ctypes.Union):
987
+ _fields_ = [("KeyEvent", _KeyEvent), ("_pad", ctypes.c_byte * 16)]
988
+
989
+ class _InputRecord(ctypes.Structure):
990
+ _fields_ = [("EventType", wintypes.WORD), ("Event", _Event)]
991
+
992
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
993
+ kernel32.FlushConsoleInputBuffer.argtypes = [wintypes.HANDLE]
994
+ kernel32.WriteConsoleInputW.argtypes = [
995
+ wintypes.HANDLE, ctypes.POINTER(_InputRecord), wintypes.DWORD,
996
+ ctypes.POINTER(wintypes.DWORD)]
997
+ kernel32.FlushConsoleInputBuffer(handle)
998
+
999
+ key_event, vk_escape = 0x0001, 0x1B
1000
+ records = (_InputRecord * 2)()
1001
+ for record, down in zip(records, (True, False)):
1002
+ record.EventType = key_event
1003
+ record.Event.KeyEvent.bKeyDown = down
1004
+ record.Event.KeyEvent.wRepeatCount = 1
1005
+ record.Event.KeyEvent.wVirtualKeyCode = vk_escape
1006
+ record.Event.KeyEvent.uChar.UnicodeChar = "\x1b"
1007
+ written = wintypes.DWORD()
1008
+ kernel32.WriteConsoleInputW(handle, records, 2, ctypes.byref(written))
1009
+
1010
+
344
1011
  class _StdinReader:
345
1012
  """The ONE reader of stdin in this process (ROADMAP_v2 §29, N1).
346
1013
 
@@ -372,6 +1039,23 @@ class _StdinReader:
372
1039
  immediately. A `drain=` flag would put that safety rule one keyword
373
1040
  argument away from being switched off at an approval prompt, which
374
1041
  is why these are two methods and not one.
1042
+
1043
+ BATCH 121 AMENDS THE RULE TO "ONE READER AT A TIME", which is what it
1044
+ always meant. N1 is scoped to this MODULE, and the biggest reader of
1045
+ this process's stdin is not in it: Textual's win32.EventMonitor reads
1046
+ the same console from its own thread. A pump parked in a blocking read
1047
+ when the TUI starts therefore takes every keystroke -- the owner's
1048
+ report is a TUI that animates and accepts no input at all, mouse and
1049
+ Ctrl keys included, after the trust prompt. Measured in a console of
1050
+ its own: an EventMonitor-shaped loop saw 0 of 5 injected characters
1051
+ with the pump parked, and 5 of 5 without it.
1052
+
1053
+ So the pump is no longer started for a read that needs no thread.
1054
+ readline() reads INLINE when none exists, which leaves nothing parked
1055
+ for a one-shot startup prompt, and release_terminal() is the named
1056
+ point where this process stops being stdin's reader at all. ask()
1057
+ still starts one: a deadline cannot be imposed on a read that cannot
1058
+ be abandoned, and that is the whole reason the thread exists.
375
1059
  """
376
1060
 
377
1061
  # N3. The end of stdin is invisible to a queue consumer: input()
@@ -388,6 +1072,11 @@ class _StdinReader:
388
1072
  self._lines = queue.Queue()
389
1073
  self._thread = None
390
1074
  self._eof = threading.Event()
1075
+ # Batch 121. Set once this process has handed the terminal to
1076
+ # something else, which today means Textual. Separate from _eof
1077
+ # because the reasons differ -- stdin ENDED versus stdin is no
1078
+ # longer ours to read -- even though both answers are the same.
1079
+ self._released = False
391
1080
 
392
1081
  def _pump(self):
393
1082
  try:
@@ -408,15 +1097,95 @@ class _StdinReader:
408
1097
  self._lines.put(self._EOF)
409
1098
 
410
1099
  def _start(self) -> None:
1100
+ """Start the pump, unless the terminal is no longer ours.
1101
+
1102
+ Batch 121: the refusal is the half that makes release_terminal()
1103
+ a handover rather than a note. Starting a pump after the TUI has
1104
+ the console is the defect itself, one call site later.
1105
+ """
1106
+ if self._released:
1107
+ return
411
1108
  if self._thread is None:
412
1109
  import threading
413
1110
  self._thread = threading.Thread(target=self._pump, daemon=True)
414
1111
  self._thread.start()
415
1112
 
1113
+ def release_terminal(self) -> bool:
1114
+ """Stop being this terminal's reader. Returns whether that is true.
1115
+
1116
+ Batch 121. Called once, immediately before Textual takes the
1117
+ console. Every later read answers the way it answers a closed
1118
+ stdin, because a terminal this process no longer owns is exactly
1119
+ a stdin nobody can type at -- EOFError out of readline() and None
1120
+ out of ask(), both of which already route to a declining default.
1121
+
1122
+ FALSE MEANS A PUMP IS STILL PARKED IN A READ, which cannot be
1123
+ interrupted on any platform this runs on. Nothing can produce
1124
+ that today: the only two prompts that run before the TUI go
1125
+ through readline(), which no longer starts one. It is reported
1126
+ rather than asserted because the symptom it would otherwise
1127
+ produce is a UI that animates and ignores the keyboard, with
1128
+ nothing anywhere saying why.
1129
+ """
1130
+ self._released = True
1131
+ # The latch and the sentinel, for the same reason N3 published
1132
+ # both: anyone already waiting on the queue has to be woken, and
1133
+ # ask()'s drain would swallow a lone sentinel.
1134
+ self._eof.set()
1135
+ self._lines.put(self._EOF)
1136
+ thread = self._thread
1137
+ return thread is None or not thread.is_alive()
1138
+
416
1139
  def _ended(self) -> bool:
417
1140
  """stdin is closed AND nothing typed before it closed is left."""
418
1141
  return self._eof.is_set() and self._lines.empty()
419
1142
 
1143
+ @staticmethod
1144
+ def _flush_terminal() -> None:
1145
+ """Discard what was typed at a real terminal and not yet read
1146
+ (ROADMAP_v3 §88, A83; TECHNICAL_DEBT 44).
1147
+
1148
+ ask()'s drain empties the QUEUE, which holds only what the pump has
1149
+ already taken. Measured in a console of its own, three things got
1150
+ past it: a line typed before the first ask() of a process, which
1151
+ the pump had not started reading yet; half a line typed before it,
1152
+ which became the front of the real answer ("sta" + "fresh"); and
1153
+ half a line typed between two questions, which the pump, parked in
1154
+ a read, was still holding unfinished. All three are input typed
1155
+ before the question was asked, and none is an answer to it.
1156
+
1157
+ POSIX: `tcflush(TCIFLUSH)` discards all three, the half line in the
1158
+ line discipline included. Windows: `FlushConsoleInputBuffer`
1159
+ discards the first two, and NOT the third -- a cooked read already
1160
+ in progress holds its half line in its own edit buffer, out of the
1161
+ input buffer's reach. So one Escape key is written after the flush:
1162
+ conhost's cooked read clears its edit line on Escape, echo included,
1163
+ and with no read in progress the pump's next read clears an empty
1164
+ line, which does nothing. Measured: all three cases clean on both
1165
+ platforms, and a line typed after the prompt still answers it.
1166
+
1167
+ Only a real terminal. Piped stdin is input someone wrote down on
1168
+ purpose, and flushing it would throw away a script's answers. Best
1169
+ effort, like the drain it sits beside: a failure is logged and the
1170
+ question is still asked.
1171
+ """
1172
+ try:
1173
+ if not sys.stdin.isatty():
1174
+ return
1175
+ fd = sys.stdin.fileno()
1176
+ except (AttributeError, OSError, ValueError):
1177
+ return
1178
+ try:
1179
+ if os.name == "nt":
1180
+ import msvcrt
1181
+ handle = msvcrt.get_osfhandle(fd)
1182
+ _flush_console_input(handle)
1183
+ else:
1184
+ import termios
1185
+ termios.tcflush(fd, termios.TCIFLUSH)
1186
+ except Exception as e: # noqa: BLE001 -- best effort, as the drain is
1187
+ logger.debug("could not flush the terminal's input: %s", e)
1188
+
420
1189
  def ask(self, prompt: str, timeout: float | None = None):
421
1190
  """Returns the typed line, or None if nobody answered in time.
422
1191
 
@@ -427,6 +1196,16 @@ class _StdinReader:
427
1196
  """
428
1197
  import queue as _queue
429
1198
 
1199
+ if self._released:
1200
+ # Batch 121. Nobody can answer a prompt at a terminal this
1201
+ # process has handed over, and None is this method's existing
1202
+ # word for that -- interaction.decode turns it into the
1203
+ # kind's declining default.
1204
+ return None
1205
+ # §88 (A83): the terminal's own buffer first, and BEFORE the pump
1206
+ # can start, so on a process's first ask() there is nothing left
1207
+ # for it to read; then the queue, for what it already took.
1208
+ self._flush_terminal()
430
1209
  self._start()
431
1210
  while True: # drop anything typed too late
432
1211
  try:
@@ -456,9 +1235,38 @@ class _StdinReader:
456
1235
  keeps whatever was typed ahead, strips the trailing newline, and
457
1236
  raises EOFError on Ctrl+D so run_chat's existing handler and
458
1237
  _ask's default-No path are unchanged.
1238
+
1239
+ BATCH 121: READS ON THE CALLING THREAD WHEN NO PUMP EXISTS. This
1240
+ method needs no thread -- it has no deadline (N2), so there is
1241
+ nothing to abandon a blocked read FOR -- and starting one anyway
1242
+ is what left the trust prompt's pump parked in a read for the
1243
+ life of the process. The TUI then shared the console with it and
1244
+ lost every keystroke.
1245
+
1246
+ Once a pump exists the queue path is taken unchanged, which is
1247
+ what keeps #100 fixed: the chat prompt must never read stdin
1248
+ directly while the approval pump owns it. So the invariant is
1249
+ "one reader at a time", and the branch is how it is kept rather
1250
+ than a special case -- the pump is authoritative the moment it
1251
+ exists, and before that there is nothing to contend with.
1252
+
1253
+ Type-ahead survives the inline path for free: a line typed early
1254
+ is held by the TERMINAL's own buffer, and a read issued later
1255
+ returns it immediately. That was always what buffered it; the
1256
+ queue only ever held what the pump had already taken out.
459
1257
  """
460
- self._start()
1258
+ if self._released:
1259
+ # The terminal belongs to something else now. Same answer as
1260
+ # a closed stdin, and _ask's caller already handles it.
1261
+ raise EOFError
461
1262
  print(prompt, end="", flush=True)
1263
+ # NO _start() HERE, and that absence is the fix. This method has no
1264
+ # deadline (N2), so there is nothing a thread could be abandoned
1265
+ # FOR -- while starting one leaves a read parked on the terminal
1266
+ # for the life of the process. A pump that already exists is
1267
+ # authoritative, because then it IS the one reader.
1268
+ if self._thread is None:
1269
+ return self._read_inline()
462
1270
  if self._ended():
463
1271
  raise EOFError
464
1272
  line = self._lines.get()
@@ -466,6 +1274,134 @@ class _StdinReader:
466
1274
  raise EOFError
467
1275
  return line.rstrip("\r\n")
468
1276
 
1277
+ def _read_inline(self) -> str:
1278
+ """One line, on this thread, leaving no reader behind.
1279
+
1280
+ A stdin that cannot be READ is a stdin that has ENDED, which is
1281
+ _pump's own wording for the same case and the same reason: under
1282
+ pytest's capture the read raises, and the callers of this have
1283
+ one handler for "nobody answered" rather than two.
1284
+ """
1285
+ try:
1286
+ line = sys.stdin.readline()
1287
+ except Exception as e:
1288
+ logger.debug("stdin could not be read: %s", e)
1289
+ self._eof.set()
1290
+ raise EOFError
1291
+ if not line:
1292
+ self._eof.set()
1293
+ raise EOFError
1294
+ return line.rstrip("\r\n")
1295
+
1296
+ def readline_masked(self, prompt: str):
1297
+ """`readline`, with the terminal not echoing (ROADMAP_v3 §49,
1298
+ slice 5a, SS59).
1299
+
1300
+ Returns the typed line, or None when there is no terminal to
1301
+ type it on, the terminal cannot hide it, or stdin ended.
1302
+
1303
+ WHY NOT `getpass.getpass`: it reads stdin ITSELF -- character
1304
+ by character through `msvcrt` on Windows -- which would be a
1305
+ SECOND reader of the one stdin this class exists to be the only
1306
+ reader of. Audit #100 is what that costs, and a password prompt
1307
+ is the worst place to reintroduce it: the pump would take the
1308
+ passphrase and `getpass` would wait for a line nobody is going
1309
+ to type.
1310
+
1311
+ So the READ is the ordinary one and only the ECHO changes,
1312
+ which is a property of the terminal rather than of whoever is
1313
+ reading. The pump still delivers the line; the console simply
1314
+ does not draw it on the way past.
1315
+
1316
+ NOT A TTY MEANS NO ANSWER, deliberately. A redirected stdin has
1317
+ no echo to turn off, so a passphrase typed into one would land
1318
+ in the pipe, the scrollback and any log capturing the run.
1319
+ None routes that to `interaction.decode`'s declining default,
1320
+ which is a refusal the user can see rather than a secret they
1321
+ cannot take back.
1322
+ """
1323
+ try:
1324
+ if not sys.stdin.isatty():
1325
+ return None
1326
+ except (AttributeError, ValueError):
1327
+ return None
1328
+ self._start()
1329
+ print(prompt, end="", flush=True)
1330
+ if self._ended():
1331
+ print()
1332
+ return None
1333
+ restore = _echo_off()
1334
+ if restore is None:
1335
+ print()
1336
+ print(" [this terminal cannot hide what you type; "
1337
+ "nothing was read]")
1338
+ return None
1339
+ try:
1340
+ line = self._lines.get()
1341
+ finally:
1342
+ restore()
1343
+ # The newline the terminal did not echo on Enter.
1344
+ print()
1345
+ if line is self._EOF:
1346
+ return None
1347
+ return line.rstrip("\r\n")
1348
+
1349
+
1350
+ def _echo_off():
1351
+ """Turn the terminal's echo off; return a callable restoring it, or
1352
+ None when this terminal cannot do it.
1353
+
1354
+ Two implementations because there is no portable one, and each is
1355
+ the platform's own mechanism rather than a library that would read
1356
+ stdin on our behalf -- which is the whole point of doing it here.
1357
+ """
1358
+ if os.name == "nt":
1359
+ try:
1360
+ import ctypes
1361
+ from ctypes import wintypes
1362
+ except ImportError: # pragma: no cover
1363
+ return None
1364
+ try:
1365
+ kernel32 = ctypes.windll.kernel32
1366
+ handle = kernel32.GetStdHandle(-10) # STD_INPUT_HANDLE
1367
+ mode = wintypes.DWORD()
1368
+ if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
1369
+ return None
1370
+ enable_echo_input = 0x0004
1371
+ if not kernel32.SetConsoleMode(
1372
+ handle, mode.value & ~enable_echo_input):
1373
+ return None
1374
+ except (AttributeError, OSError): # pragma: no cover
1375
+ return None
1376
+
1377
+ def restore():
1378
+ kernel32.SetConsoleMode(handle, mode.value)
1379
+
1380
+ return restore
1381
+ try:
1382
+ import termios
1383
+ except ImportError: # pragma: no cover
1384
+ return None
1385
+ try:
1386
+ fd = sys.stdin.fileno()
1387
+ before = termios.tcgetattr(fd)
1388
+ except (ValueError, OSError, termios.error):
1389
+ return None
1390
+ after = list(before)
1391
+ after[3] = after[3] & ~termios.ECHO # lflags
1392
+ try:
1393
+ termios.tcsetattr(fd, termios.TCSADRAIN, after)
1394
+ except (OSError, termios.error):
1395
+ return None
1396
+
1397
+ def restore():
1398
+ try:
1399
+ termios.tcsetattr(fd, termios.TCSADRAIN, before)
1400
+ except (OSError, termios.error):
1401
+ pass # the terminal is gone or no longer a tty; nothing to restore
1402
+
1403
+ return restore
1404
+
469
1405
 
470
1406
  _STDIN_READER: "_StdinReader | None" = None
471
1407
 
@@ -482,6 +1418,19 @@ def _stdin_reader() -> _StdinReader:
482
1418
  return _STDIN_READER
483
1419
 
484
1420
 
1421
+ def _release_terminal() -> bool:
1422
+ """Hand stdin over, for a reader that may never have been built.
1423
+
1424
+ Batch 121. Reads the global rather than going through _stdin_reader(),
1425
+ because that function CREATES one -- and a launch with no startup
1426
+ prompt has nothing to release. Returns whether the terminal is
1427
+ genuinely free; see _StdinReader.release_terminal.
1428
+ """
1429
+ if _STDIN_READER is None:
1430
+ return True
1431
+ return _STDIN_READER.release_terminal()
1432
+
1433
+
485
1434
  def build_attended_provider(honour_run_scope: bool = False,
486
1435
  timeout=_DEFAULT_TIMEOUT):
487
1436
  """A ResponseChannel that asks at the terminal (§25 R9, §23 AC1).
@@ -529,8 +1478,44 @@ def build_attended_provider(honour_run_scope: bool = False,
529
1478
  for line in rendered.splitlines():
530
1479
  print(f" {line}")
531
1480
 
1481
+ def _asker(payload: dict, visible) -> None:
1482
+ """Name the run that raised this, when it is not the conversation.
1483
+
1484
+ §47 put `asking_agent` / `asking_depth` on every payload that can
1485
+ be raised from inside a run -- core/loop.py writes them onto an
1486
+ approval, and the `ask_user` tool onto a question -- and rendered
1487
+ them in the TUI only. This shell dropped all three, which is the
1488
+ gap `_approval` below names in its own comment: a kind one shell
1489
+ renders and the other drops looks perfectly wired up (D12). Found
1490
+ by the second round of reviewing §47, batch 76.
1491
+
1492
+ It matters most where the subject of the question is a NAME. NA9
1493
+ means three children of one response can each be spawning a
1494
+ grandchild, and their three sign-offs name the grandchild and
1495
+ nothing else -- three identical prompts on the one stdin reader.
1496
+
1497
+ DIRECTLY UNDER THE BRACKETED HEADER, above the candidates or the
1498
+ payload, at every site: one placement rule rather than three, and
1499
+ the same position relative to the header that the modal gives it.
1500
+
1501
+ Silent at depth 0, which is SCOPE rather than a gap -- the asking
1502
+ run is then the conversation being watched.
1503
+ """
1504
+ asked_by = payload.get("asking_agent")
1505
+ if asked_by:
1506
+ print(f" asked by {visible(asked_by)} "
1507
+ f"(depth {payload.get('asking_depth') or 0})")
1508
+
532
1509
  def _approval(request) -> bool:
533
- print(f"\n[approval] {request.payload.get('tool_name')}")
1510
+ # Every untrusted field below goes through one `visible`
1511
+ # (batch 152), and `visible.warn()` is what tells the user that
1512
+ # something did. `reveal=True` since batch 160: this is the one
1513
+ # prompt where a person authorises what the text says.
1514
+ visible = _Visible(reveal=True)
1515
+ print(f"\n[approval] {visible(request.payload.get('tool_name'))}")
1516
+ # Under the header, above everything the agent wrote -- see
1517
+ # `_asker`, which is the one placement rule for the three kinds.
1518
+ _asker(request.payload, visible)
534
1519
  # §46 (EP1). The subject of the question, first. The TUI pins it
535
1520
  # because a modal has a bottom edge; a terminal does not, so
536
1521
  # here it is placement rather than rescue -- but a kind one
@@ -539,10 +1524,15 @@ def build_attended_provider(honour_run_scope: bool = False,
539
1524
  # both. None for every tool that declares no headline.
540
1525
  headline = request.payload.get("headline")
541
1526
  if headline:
1527
+ # `splitlines()` splits on a carriage return as well as a
1528
+ # newline, so a CR in a headline became a second $-prefixed
1529
+ # line rather than an overwrite even before this batch --
1530
+ # measured, and the doubled prefix is what showed it. The
1531
+ # escape is what did the damage.
542
1532
  for line in str(headline).splitlines():
543
- print(f" $ {line}")
1533
+ print(f" $ {visible(line)}")
544
1534
  if request.notice:
545
- print(f" {request.notice}")
1535
+ print(f" {visible(request.notice)}")
546
1536
  # §42 (RA6). Same order as the modal -- the computed notice,
547
1537
  # then the agent's own claim, then the payload. Shown here as
548
1538
  # well as in the TUI because a kind one shell renders and the
@@ -550,8 +1540,10 @@ def build_attended_provider(honour_run_scope: bool = False,
550
1540
  # and the CLI is where an unattended-looking run is watched
551
1541
  # from.
552
1542
  reason = request.payload.get("rationale")
553
- print(f" reason (the agent's own words, unverified): {reason or '(none given)'}")
1543
+ print(" reason (the agent's own words, unverified): "
1544
+ f"{visible(reason) if reason else '(none given)'}")
554
1545
  _render_params(request.payload.get("params") or {})
1546
+ visible.warn()
555
1547
  answer = reader.ask(f" Allow? [y/N]{clock}: ", timeout)
556
1548
  if answer is None:
557
1549
  print(" [no answer — denied; the run continues]")
@@ -577,9 +1569,16 @@ def build_attended_provider(honour_run_scope: bool = False,
577
1569
  multi = bool(payload.get("multi_select"))
578
1570
  allow_text = payload.get("allow_text", True) is not False
579
1571
 
580
- print(f"\n[question] {payload.get('question', '')}")
1572
+ visible = _Visible()
1573
+ print(f"\n[question] {visible(payload.get('question', ''))}")
1574
+ # The one site where the header already carries the model's own
1575
+ # words, so the label follows them rather than preceding them --
1576
+ # the same order `_approval` keeps for its headline, and for the
1577
+ # reason its comment gives: a terminal has no bottom edge, so
1578
+ # this is placement rather than rescue.
1579
+ _asker(payload, visible)
581
1580
  for index, option in enumerate(options, start=1):
582
- print(f" {index}. {option}")
1581
+ print(f" {index}. {visible(option)}")
583
1582
  how = []
584
1583
  if options:
585
1584
  how.append("numbers separated by spaces" if multi else "a number")
@@ -588,6 +1587,7 @@ def build_attended_provider(honour_run_scope: bool = False,
588
1587
  how.append("'d' to discuss it instead")
589
1588
  prompt = f" {', or '.join(how)} (blank to skip): "
590
1589
 
1590
+ visible.warn()
591
1591
  answer = reader.ask(prompt, timeout)
592
1592
  if answer is None:
593
1593
  print(" [no answer — the model will be told nobody replied]")
@@ -624,18 +1624,28 @@ def build_attended_provider(honour_run_scope: bool = False,
624
1624
  so out loud beats leaving the user to infer it from a spawn that
625
1625
  quietly did not happen.
626
1626
  """
1627
+ visible = _Visible()
627
1628
  agent = request.payload.get("agent", "the subagent")
628
1629
  candidates = list(request.payload.get("candidates") or [])
629
1630
  if not candidates:
630
- print(f"\n[subagent] {agent} needs no approval-gated tools.")
1631
+ print(f"\n[subagent] {visible(agent)} needs no approval-gated "
1632
+ "tools.")
1633
+ # BOTH branches, as the modal splices it into both of its own:
1634
+ # a nested spawn of an agent with no gated tools reaches this
1635
+ # one, and `agent` here is the run about to be SPAWNED.
1636
+ _asker(request.payload, visible)
1637
+ visible.warn()
631
1638
  answer = reader.ask(f" Run it? [y/N]{clock}: ", timeout)
632
1639
  if answer and answer.strip().lower() in ("y", "yes"):
633
1640
  return set()
634
1641
  print(" [the spawn was refused]")
635
1642
  return None
636
- print(f"\n[subagent] {agent} may be granted, for this turn only:")
1643
+ print(f"\n[subagent] {visible(agent)} may be granted, for this "
1644
+ "turn only:")
1645
+ _asker(request.payload, visible)
637
1646
  for index, name in enumerate(candidates, 1):
638
- print(f" {index}. {name}")
1647
+ print(f" {index}. {visible(name)}")
1648
+ visible.warn()
639
1649
  answer = reader.ask(
640
1650
  " Grant which? [numbers / 'all' / 'none' / blank to refuse]"
641
1651
  f"{clock}: ", timeout)
@@ -655,6 +1665,18 @@ def build_attended_provider(honour_run_scope: bool = False,
655
1665
  chosen.add(candidates[int(piece) - 1])
656
1666
  else:
657
1667
  print(f" [ignoring {piece!r} — not one of the numbers above]")
1668
+ if not chosen:
1669
+ # NOTHING IN THAT LINE NAMED A TOOL (batch 152), and the
1670
+ # empty set is already taken: it is the explicit `none`, which
1671
+ # returned
1672
+ # above, and `core/loop.py` spawns on "not None". So returning
1673
+ # `chosen` here turned a mistyped refusal into an
1674
+ # authorisation to spawn -- measured, `xyz` and `0 99` both
1675
+ # spawned. This is the docstring's own "None for anything
1676
+ # unparsed is belt-and-braces", which the code did for a blank
1677
+ # line and not for a line it could not read.
1678
+ print(" [nothing there named a tool — the spawn was refused]")
1679
+ return None
658
1680
  return chosen
659
1681
 
660
1682
  def _confirm(request):
@@ -665,12 +1687,14 @@ def build_attended_provider(honour_run_scope: bool = False,
665
1687
  shell how to render: an approval is a gated tool call with params,
666
1688
  this is prose someone wants signed off.
667
1689
  """
1690
+ visible = _Visible()
668
1691
  payload = request.payload
669
1692
  body = payload.get("body", "")
670
1693
  if body:
671
- print(f"\n{body}")
672
- answer = reader.ask(
673
- f" {payload.get('title', 'Proceed?')} [y/N]{clock}: ", timeout)
1694
+ print(f"\n{visible(body)}")
1695
+ title = visible(payload.get("title", "Proceed?"))
1696
+ visible.warn()
1697
+ answer = reader.ask(f" {title} [y/N]{clock}: ", timeout)
674
1698
  if answer is None:
675
1699
  print(" [no answer — nothing was done]")
676
1700
  return False
@@ -686,16 +1710,24 @@ def build_attended_provider(honour_run_scope: bool = False,
686
1710
  makes `s` mean software without anything hard-coding it), or a
687
1711
  bare Enter to take the suggestion.
688
1712
  """
1713
+ visible = _Visible()
689
1714
  payload = request.payload
690
1715
  options = [str(o) for o in (payload.get("options") or ())]
691
1716
  proposal = payload.get("proposal")
692
1717
  if payload.get("blank"):
693
1718
  print("\nThis folder is empty, so there is nothing to go on.")
694
1719
  elif proposal:
695
- print(f"\nThis looks like a {proposal} project — "
696
- f"{payload.get('reason', 'no reason given')}.")
697
- labels = " or ".join(f"[{o[:1]}]{o[1:]}" for o in options)
1720
+ print(f"\nThis looks like a {visible(proposal)} project — "
1721
+ f"{visible(payload.get('reason', 'no reason given'))}.")
1722
+ # The LABELS are scrubbed and the returned value is not: what this
1723
+ # kind answers with has to be the option as it was offered, since
1724
+ # decode validates the answer against that list (and a scrubbed
1725
+ # answer would fail that check for the one reason that is not the
1726
+ # user's fault).
1727
+ labels = " or ".join(f"[{o[:1]}]{o[1:]}" for o in
1728
+ (visible(o) for o in options))
698
1729
  accepts = " (enter accepts the suggestion)" if proposal else ""
1730
+ visible.warn()
699
1731
  answer = reader.ask(f" {labels}?{accepts}{clock}: ", timeout)
700
1732
  if answer is None:
701
1733
  print(" [no answer — nothing was chosen]")
@@ -711,7 +1743,11 @@ def build_attended_provider(honour_run_scope: bool = False,
711
1743
  if o.lower().startswith(cleaned.lower())]
712
1744
  if len(matched) == 1:
713
1745
  return matched[0]
714
- print(f" [{cleaned!r} is not one of: {', '.join(options)}]")
1746
+ # The SECOND rendering of the same list, and the one a reader
1747
+ # does not think of as display -- found by the relation test
1748
+ # rather than by reading this function (batch 152).
1749
+ print(f" [{cleaned!r} is not one of: "
1750
+ f"{', '.join(visible(o) for o in options)}]")
715
1751
  return None
716
1752
 
717
1753
  def _review(request):
@@ -730,8 +1766,33 @@ def build_attended_provider(honour_run_scope: bool = False,
730
1766
  # perfectly wired up. CONFIRM and CHOICE sat in that state through two
731
1767
  # sections. A runtime warning would only fire once someone reached the
732
1768
  # branch, which is exactly the condition nobody noticed.
1769
+ def _secret(request):
1770
+ """SS59 on the CLI. Masked, and it names nothing it reads.
1771
+
1772
+ A missing branch here is audit #7's shape -- the kind falls
1773
+ through to None, decode turns that into the declining default,
1774
+ and the feature reports "nobody answered" on every CLI run
1775
+ while looking perfectly wired up. The parity test against
1776
+ `interaction.SAFE_DEFAULTS` is what makes adding a kind
1777
+ without this a FAILURE rather than a later discovery.
1778
+ """
1779
+ visible = _Visible()
1780
+ payload = request.payload
1781
+ print()
1782
+ print(visible(payload.get("title", "Enter a secret")))
1783
+ body = payload.get("body", "")
1784
+ if body:
1785
+ print(visible(body))
1786
+ visible.warn()
1787
+ answer = reader.readline_masked(" (not shown as you type): ")
1788
+ if answer is None:
1789
+ print(" [nothing was entered]")
1790
+ return None
1791
+ return answer
1792
+
733
1793
  handlers = {
734
1794
  interaction.APPROVAL: _approval,
1795
+ interaction.SECRET: _secret,
735
1796
  interaction.SUBAGENT_SIGNOFF: _signoff,
736
1797
  interaction.QUESTION: _question,
737
1798
  interaction.REVIEW: _review,
@@ -756,38 +1817,164 @@ def build_attended_provider(honour_run_scope: bool = False,
756
1817
  return channel
757
1818
 
758
1819
 
759
- def run_memory_command(args) -> int:
760
- """`--memories` / `--forget`, ROADMAP_v2 §21b (M15).
1820
+ def run_secrets_command(args) -> int:
1821
+ """`--secrets ...`, ROADMAP_v3 §49 slice 5a (SS56-SS62).
761
1822
 
762
- Listing exists to make removal usable: the model never shows ids, so
763
- without it `--forget` has nothing to be given. Both print the SCOPE of
764
- each row, because "which of these follows me to another project" is the
765
- question a user pruning memories is actually asking.
1823
+ Runs no model, touches no thread, and exits -- beside --memories for
1824
+ that reason.
1825
+
1826
+ EVERY VALUE IS READ AT A MASKED PROMPT AND NONE IS TAKEN FROM ARGV.
1827
+ That is not a convenience: on every platform this runs on, another
1828
+ process can read this one's command line, and on a shell it also lands
1829
+ in the history file. A `--secrets set name VALUE` spelling would have
1830
+ been shorter and would have leaked the secret to disk before the store
1831
+ ever encrypted it.
1832
+
1833
+ Prints names, counts and outcomes. Never a value (SS62).
766
1834
  """
767
- from memories.manager import manager as memory_manager
768
- from storage import forget_memory
1835
+ from security import secrets
769
1836
 
770
- if args.forget:
1837
+ parts = list(args.secrets)
1838
+ verb = parts[0].lower()
1839
+ rest = parts[1:]
1840
+ reader = _stdin_reader()
1841
+
1842
+ def ask(prompt: str):
1843
+ value = reader.readline_masked(prompt)
1844
+ if value is None:
1845
+ print(" [nothing was entered]")
1846
+ return value
1847
+
1848
+ def unlocked() -> bool:
1849
+ if secrets.is_unlocked():
1850
+ return True
1851
+ if not secrets.exists():
1852
+ print(f"No secrets store. --secrets set <name> creates one at "
1853
+ f"{secrets.store_path()}.")
1854
+ return False
1855
+ answer = ask("Master passphrase (not shown as you type): ")
1856
+ if not answer:
1857
+ return False
771
1858
  try:
772
- memory_id = UUID(args.forget)
773
- except ValueError:
774
- print(f"Not a memory id: {args.forget!r}. Run --memories to list them.")
1859
+ secrets.unlock(answer)
1860
+ except secrets.StoreUnreadable as exc:
1861
+ # ABOVE the SecretsError arm, and it cannot be otherwise: a
1862
+ # subclass has to be caught first or the base arm takes it.
1863
+ # That ordering is not what makes this safe, though -- the TYPE
1864
+ # is. `WrongPassphrase` is deliberately NOT a StoreUnreadable,
1865
+ # so the recovery text cannot reach someone who simply typed
1866
+ # their passphrase wrong (batch 108).
1867
+ print(f"[error] {exc}")
1868
+ print(secrets.recovery_hint())
1869
+ return False
1870
+ except secrets.SecretsError as exc:
1871
+ print(f"[error] {exc}")
1872
+ return False
1873
+ return True
1874
+
1875
+ if verb == "status":
1876
+ if not secrets.exists():
1877
+ print(f"No secrets store. It would live at "
1878
+ f"{secrets.store_path()}.")
1879
+ else:
1880
+ print(f"Secrets store present at {secrets.store_path()}.")
1881
+ return 0
1882
+
1883
+ if verb == "list":
1884
+ if not unlocked():
775
1885
  return 1
776
- if forget_memory(memory_id):
777
- print(f"Forgot {memory_id}.")
1886
+ entries = secrets.names()
1887
+ if not entries:
1888
+ print("No secrets stored.")
1889
+ else:
1890
+ print("Stored secrets (names only):")
1891
+ for name in entries:
1892
+ print(f" {name}")
1893
+ return 0
1894
+
1895
+ if verb == "delete":
1896
+ if not rest:
1897
+ print("Usage: --secrets delete <name>")
1898
+ return 2
1899
+ if not unlocked():
1900
+ return 1
1901
+ if secrets.delete(rest[0]):
1902
+ print(f"Deleted {rest[0]}.")
778
1903
  return 0
779
- print(f"No memory with id {memory_id}.")
1904
+ print(f"No secret named {rest[0]}.")
780
1905
  return 1
781
1906
 
782
- rows = memory_manager.visible()
783
- if not rows:
784
- where = memory_manager.scope_path() or "(no project resolved)"
785
- print(f"No durable memories visible from {where}.")
1907
+ if verb == "set":
1908
+ if not rest:
1909
+ print("Usage: --secrets set <name>")
1910
+ return 2
1911
+ name = rest[0]
1912
+ if not secrets.exists():
1913
+ print("Creating a new secrets store. There is no recovery for "
1914
+ "a forgotten passphrase: delete the file and start again.")
1915
+ first = ask("Choose a master passphrase: ")
1916
+ if not first:
1917
+ return 1
1918
+ try:
1919
+ secrets.create(first)
1920
+ except secrets.SecretsError as exc:
1921
+ print(f"[error] {exc}")
1922
+ return 1
1923
+ elif not unlocked():
1924
+ return 1
1925
+ value = ask(f"Value for {name}: ")
1926
+ if not value:
1927
+ return 1
1928
+ try:
1929
+ secrets.put(name, value)
1930
+ except secrets.SecretsError as exc:
1931
+ print(f"[error] {exc}")
1932
+ return 1
1933
+ print(f"Saved {name}.")
1934
+ # SS58's reuse offer, in the CLI's own idiom.
1935
+ twin = _secret_twin_name(name)
1936
+ if twin:
1937
+ answer = _ask(f"Also save the same value as {twin}? [y/N]: ")
1938
+ if answer.strip().lower().startswith("y"):
1939
+ try:
1940
+ secrets.put(twin, value)
1941
+ except secrets.SecretsError as exc:
1942
+ print(f"[error] {exc}")
1943
+ return 1
1944
+ print(f"Saved {twin}.")
786
1945
  return 0
787
- for row in rows:
788
- marker = "global " if row["scope"] == "global" else "project"
789
- category = f" [{row['category']}]" if row.get("category") else ""
790
- print(f"{row['id']} {marker}{category} {row['content']}")
1946
+
1947
+ print("Usage: --secrets status | list | set <name> | delete <name>")
1948
+ return 2
1949
+
1950
+
1951
+ def _secret_twin_name(name: str):
1952
+ """`ssh.<host>.login` <-> `ssh.<host>.sudo` (SS58).
1953
+
1954
+ Mirrors `tui/app.py`'s `_secret_twin` rather than importing it: main.py
1955
+ does not import the TUI module at all, and doing so to share nine lines
1956
+ would pull Textual into every CLI run. `tests/test_secrets.py` holds
1957
+ the two against each other, so drift is a failure rather than a hole.
1958
+ """
1959
+ for left, right in (("login", "sudo"), ("sudo", "login")):
1960
+ if name.endswith("." + left):
1961
+ return name[: -len(left)] + right
1962
+ return None
1963
+
1964
+
1965
+ def run_memory_command(args) -> int:
1966
+ """`--memories` / `--forget`, ROADMAP_v2 §21b (M15).
1967
+
1968
+ Listing exists to make removal usable: the model never shows ids, so
1969
+ without it `--forget` has nothing to be given. Both print the SCOPE of
1970
+ each row, because "which of these follows me to another project" is the
1971
+ question a user pruning memories is actually asking.
1972
+ """
1973
+ # cli_commands prints both, so the flags and /memories and /forget
1974
+ # cannot come to list or refuse two ways (§89).
1975
+ if args.forget:
1976
+ return 0 if forget_memory(args.forget, "--memories") else 1
1977
+ print_memories()
791
1978
  return 0
792
1979
 
793
1980
 
@@ -827,7 +2014,8 @@ def run_summary_command(args, provider_name: str, model: str) -> int:
827
2014
  def run_init_command(args, provider_name: str, model: str) -> int:
828
2015
  """`--init`, ROADMAP_v2 §24 (M21's precedent again).
829
2016
 
830
- A flag rather than a slash command because the CLI has no command layer;
2017
+ A flag because the CLI had no command layer when it was written, and
2018
+ `/init` is still not one of its commands (core/commands.py says why);
831
2019
  everything else -- which document set, whether an existing file is
832
2020
  overwritten, whether workspace trust is re-granted -- is decided in
833
2021
  project_init.generator, exactly as it is for the TUI's /init.
@@ -895,9 +2083,17 @@ def run_init_command(args, provider_name: str, model: str) -> int:
895
2083
  scaffold_config=args.project_config,
896
2084
  )
897
2085
  except InitError as e:
898
- print(f"\n{e}")
2086
+ print(f"\n{ansi.for_display(e)}")
2087
+ return 1
2088
+ except OSError as e:
2089
+ # #255, batch 213, the owner's choice of both halves: generate()
2090
+ # turns the walks it knows about into InitError, and this catches
2091
+ # the filesystem error nobody has met yet, so the CLI ends with a
2092
+ # line, as the TUI's worker does, instead of a traceback. Not a
2093
+ # blanket Exception: a bug should still show its stack.
2094
+ print(f"\n[--init stopped: {ansi.for_display(e)}]")
899
2095
  return 1
900
- print(f"\n{notice['text']}")
2096
+ print(f"\n{ansi.for_display(notice['text'])}")
901
2097
  return 0
902
2098
 
903
2099
 
@@ -911,10 +2107,7 @@ def attach_cli_refs(thread_id, specs, provider_name: str, model: str) -> None:
911
2107
  Goes through core.loop.attach_ref, the same writer the TUI's /ref uses, so
912
2108
  the two shells cannot disagree about the cap or the stored shape.
913
2109
  """
914
- from core import compaction
915
- from core.loop import attach_ref
916
2110
  from core.memory import ConversationMemory
917
- from storage import thread_preview
918
2111
 
919
2112
  memory = ConversationMemory(thread_id=thread_id)
920
2113
  for spec in specs:
@@ -927,23 +2120,17 @@ def attach_cli_refs(thread_id, specs, provider_name: str, model: str) -> None:
927
2120
  print("[--ref: that is this thread; skipped]")
928
2121
  continue
929
2122
  try:
930
- notice = compaction.summarize_thread(source, model, provider_name)
2123
+ # #171's label and the shared writer, through the helper /ref
2124
+ # uses too (§89).
2125
+ _ok, message = attach_summary(memory, source, model,
2126
+ provider_name)
931
2127
  except Exception as e: # noqa: BLE001 -- a failed reference must not
932
2128
  # stop the session from starting.
933
2129
  logger.warning("Could not summarise thread %s: %s", source, e)
934
- print(f"[--ref: could not summarise {source}: {e}]")
2130
+ print(f"[--ref: could not summarise {source}: "
2131
+ f"{ansi.for_display(e)}]")
935
2132
  continue
936
- if notice is None:
937
- print(f"[--ref: nothing to summarise in {source}]")
938
- continue
939
- # #171. The label the TUI's picker has always attached: the same
940
- # first-user-message preview, so both shells store identical rows
941
- # and the prompt tier names what the material IS instead of
942
- # "(no preview)". Computed only after the summarise succeeded --
943
- # a failed reference stores no row to label.
944
- ok, message = attach_ref(memory, source, notice["text"],
945
- thread_preview(source))
946
- print(f"[--ref: {message}]")
2133
+ print(f"[--ref: {ansi.for_display(message)}]")
947
2134
 
948
2135
 
949
2136
  def build_chat_authorization():
@@ -989,10 +2176,17 @@ def _pick_tools_to_grant(offered) -> set:
989
2176
  print("Granting one authorises it for THIS RUN ONLY. Nothing is saved.\n")
990
2177
  granted = set()
991
2178
  for name, description in offered:
992
- print(f" {name}")
2179
+ # ONE SCRUBBER PER TOOL, because each tool is its own question.
2180
+ # Both strings are third-party: `candidates()` exists for MCP
2181
+ # tools, and its own docstring says the description IS the whole
2182
+ # of informed consent here -- which is what makes an escape in it
2183
+ # worse than an escape in an approval headline, not better.
2184
+ visible = _Visible()
2185
+ print(f" {visible(name)}")
993
2186
  if description:
994
- print(f" {description}")
995
- if _ask(f" Grant {name} for this run? [y/N]: ").strip().lower() in ("y", "yes"):
2187
+ print(f" {visible(description)}")
2188
+ visible.warn()
2189
+ if _ask(f" Grant {visible(name)} for this run? [y/N]: ").strip().lower() in ("y", "yes"):
996
2190
  granted.add(name)
997
2191
  print()
998
2192
  return granted
@@ -1048,8 +2242,13 @@ def run_research(
1048
2242
  # capability visible only in the TUI is the split this
1049
2243
  # project keeps warning about -- and it is the CLI that goes
1050
2244
  # silent for minutes inside a tool-heavy pass.
2245
+ # Every field of an event that carries TEXT carries a
2246
+ # model's or a tool's (batch 152): a pass id is composed
2247
+ # here, a tool name can be a server's, and `event.text` is a
2248
+ # trace
2249
+ # line, a tool argument digest or a tool's own error.
1051
2250
  if event.kind == "pass_start":
1052
- print(f"-> {event.pass_id}", flush=True)
2251
+ print(f"-> {ansi.for_display(event.pass_id)}", flush=True)
1053
2252
  elif event.kind == "pass_complete" and event.ok is False:
1054
2253
  # E14/#115, L6's both-shells rule. Deliberately prints
1055
2254
  # nothing: the CLI's narrative for this failure is the
@@ -1064,15 +2263,18 @@ def run_research(
1064
2263
  # made no model call is done the moment it is announced,
1065
2264
  # so an arrow promising something is starting would be
1066
2265
  # wrong.
1067
- print(f".. {event.pass_id}", flush=True)
2266
+ print(f".. {ansi.for_display(event.pass_id)}", flush=True)
1068
2267
  elif event.kind == "tool_call":
1069
- detail = f" {event.text}" if event.text else ""
1070
- print(f" > {event.tool}{detail}", flush=True)
2268
+ detail = (f" {ansi.for_display(event.text)}"
2269
+ if event.text else "")
2270
+ print(f" > {ansi.for_display(event.tool)}{detail}",
2271
+ flush=True)
1071
2272
  elif event.kind == "tool_result" and not event.ok:
1072
2273
  # Successful results print nothing: one line per call is
1073
2274
  # already the volume, and "it worked" is what the absence
1074
2275
  # of a failure line says.
1075
- print(f" x {event.tool} {event.text}", flush=True)
2276
+ print(f" x {ansi.for_display(event.tool)} "
2277
+ f"{ansi.for_display(event.text)}", flush=True)
1076
2278
  elif event.kind == "pass_activity":
1077
2279
  # For the passes that call no tools at all -- Pass 1 and
1078
2280
  # final synthesis -- this is the only sign of life
@@ -1080,7 +2282,7 @@ def run_research(
1080
2282
  # the two longest passes in the run.
1081
2283
  print(f" .. {event.chars // 1000}k chars", flush=True)
1082
2284
  elif event.kind == "trace_line":
1083
- print(f"- {event.text}", flush=True)
2285
+ print(f"- {ansi.for_display(event.text)}", flush=True)
1084
2286
  elif event.kind == "run_complete":
1085
2287
  run = event.run
1086
2288
  if run is None:
@@ -1092,7 +2294,7 @@ def run_research(
1092
2294
  "run_complete event")
1093
2295
  except Exception as e:
1094
2296
  logger.exception("Research pipeline failed")
1095
- print(f"\nPipeline failed: {e}")
2297
+ print(f"\nPipeline failed: {ansi.for_display(e)}")
1096
2298
  print("If any partial results were persisted, they can be "
1097
2299
  "inspected via the database.")
1098
2300
  raise SystemExit(1)
@@ -1102,13 +2304,14 @@ def run_research(
1102
2304
  output_dir = write_run_artifacts(run)
1103
2305
  except Exception as e:
1104
2306
  logger.exception("Could not write artifacts")
1105
- print(f"\n[Warning: could not write artifacts: {e}]")
2307
+ print("\n[Warning: could not write artifacts: "
2308
+ f"{ansi.for_display(e)}]")
1106
2309
 
1107
2310
  # §22: no "--- Trace ---" block here any more. Every line was printed
1108
2311
  # as it happened, above; reprinting them would show the whole run
1109
2312
  # twice, with the second copy looking like a different artifact.
1110
2313
  print("\n--- Report ---")
1111
- print(run.final_report)
2314
+ print(ansi.for_display(run.final_report))
1112
2315
 
1113
2316
  if run.run_id:
1114
2317
  print(f"\n[run id: {run.run_id}]")
@@ -1141,6 +2344,21 @@ def build_parser() -> argparse.ArgumentParser:
1141
2344
  metavar="UUID",
1142
2345
  help="Resume an existing conversation thread by its UUID.",
1143
2346
  )
2347
+ # ROADMAP_v3 §49 slice 5a. A flag rather than a subcommand, matching
2348
+ # --memories/--forget, which are the other data-only commands that run
2349
+ # no model call: this parser has no subparsers at the top level and
2350
+ # adding one for this would reshape every existing invocation.
2351
+ parser.add_argument(
2352
+ "--secrets",
2353
+ nargs="+",
2354
+ default=None,
2355
+ metavar="ARG",
2356
+ help="Manage the harness-held secret store and exit: "
2357
+ "status | list | set <name> | delete <name>. Values are "
2358
+ "typed at a masked prompt, never given on the command line "
2359
+ "-- an argv is visible to every process on the machine and "
2360
+ "lands in your shell history.",
2361
+ )
1144
2362
  parser.add_argument(
1145
2363
  "--mode",
1146
2364
  choices=["chat", "research"],
@@ -1267,10 +2485,12 @@ def build_parser() -> argparse.ArgumentParser:
1267
2485
  ".venastine/ content -- intended for scripts/CI where the "
1268
2486
  "interactive prompt is unavailable.",
1269
2487
  )
1270
- # ROADMAP_v2 §21b (M15). The CLI has no slash-command layer, so these
1271
- # are flags rather than /memories and /forget -- and they exist for the
1272
- # CLI specifically because M16 makes a CLI-only user able to WRITE a
1273
- # durable memory, and they would otherwise have no way to remove one.
2488
+ # ROADMAP_v2 §21b (M15). Flags because the CLI had no slash-command
2489
+ # layer then -- and they exist for the CLI specifically because M16
2490
+ # makes a CLI-only user able to WRITE a durable memory, and they would
2491
+ # otherwise have no way to remove one. ROADMAP_v3 §89 added /memories
2492
+ # and /forget mid-chat; the flags stay for a scripted run, and both
2493
+ # print through cli_commands, so they cannot list two ways.
1274
2494
  parser.add_argument(
1275
2495
  "--memories",
1276
2496
  action="store_true",
@@ -1282,11 +2502,10 @@ def build_parser() -> argparse.ArgumentParser:
1282
2502
  metavar="ID",
1283
2503
  help="Delete one durable memory by id (see --memories) and exit.",
1284
2504
  )
1285
- # ROADMAP_v2 §21c (M21). Flags rather than /summary and /ref for the same
1286
- # reason --memories is a flag: the CLI has no slash-command layer, and
1287
- # adding one is §23's business rather than this section's. The accepted
1288
- # limit is that a CLI user attaches a reference at LAUNCH -- mid-conversation
1289
- # referencing is the TUI's.
2505
+ # ROADMAP_v2 §21c (M21). Flags for the reason --memories is a flag. M21's
2506
+ # accepted limit -- a CLI user attaches a reference only at LAUNCH -- was
2507
+ # lifted by ROADMAP_v3 §89's /summary and /ref; the flags stay for a
2508
+ # scripted run, and --ref attaches through the helper /ref uses.
1290
2509
  parser.add_argument(
1291
2510
  "--summary",
1292
2511
  metavar="THREAD",
@@ -1406,16 +2625,19 @@ def _prompt_review_decision(reader, finding, round_index,
1406
2625
  """
1407
2626
  if timeout is _DEFAULT_TIMEOUT:
1408
2627
  timeout = config.ATTENDED_APPROVAL_TIMEOUT_S
1409
- kind = finding.get("kind")
1410
- target = finding.get("claim_id") or "the report"
2628
+ # Every field here is the reviewing model's own text (batch 152).
2629
+ visible = _Visible()
2630
+ kind = visible(finding.get("kind"))
2631
+ target = visible(finding.get("claim_id") or "the report")
1411
2632
  print(f"\n[review] {kind} correction to {target} "
1412
- f"(severity: {finding.get('severity', 'unknown')})")
1413
- print(f" why: {finding.get('reason', '(no reason given)')}")
1414
- print(f" proposed: {finding.get('proposed')}")
2633
+ f"(severity: {visible(finding.get('severity', 'unknown'))})")
2634
+ print(f" why: {visible(finding.get('reason', '(no reason given)'))}")
2635
+ print(f" proposed: {visible(finding.get('proposed'))}")
1415
2636
  if round_index:
1416
2637
  print(f" (refinement {round_index} of "
1417
2638
  f"{config.MAX_REVIEW_REFINEMENTS})")
1418
2639
  clock = f" ({timeout}s)" if timeout else ""
2640
+ visible.warn()
1419
2641
  answer = reader.ask(
1420
2642
  " [a]ccept / [r]eject / [f] refine <note> / [!] reject the "
1421
2643
  f"rest{clock}: ", timeout)
@@ -1499,8 +2721,8 @@ def _ask(prompt: str) -> str:
1499
2721
  def _ensure_workspace_trust(project_path: str, trust_flag: bool) -> None:
1500
2722
  """D17 one-time confirmation. Shows what would load (file list plus
1501
2723
  settings.json verbatim -- a project's settings can pick the provider
1502
- and multiply pipeline cost via ensemble_n, so approval must be
1503
- informed). Interactive y/N on a TTY; --trust-project grants for
2724
+ and multiply pipeline cost by turning on ensemble_mode, so approval
2725
+ must be informed). Interactive y/N on a TTY; --trust-project grants for
1504
2726
  scripts/CI; non-TTY without the flag skips project content with a
1505
2727
  notice instead of hanging on input()."""
1506
2728
  if workspace_trust.is_trusted(project_path):
@@ -1581,10 +2803,14 @@ def _confirm_user_level_servers(configs: dict) -> dict:
1581
2803
 
1582
2804
  for cfg in pending:
1583
2805
  if not interactive:
1584
- print(f" - {cfg.describe()}", file=sys.stderr)
2806
+ print(f" - {ansi.for_display(cfg.describe())}",
2807
+ file=sys.stderr)
1585
2808
  approved.pop(cfg.name, None)
1586
2809
  continue
1587
- print(f"\nNew MCP server in your user config:\n {cfg.describe()}")
2810
+ visible = _Visible()
2811
+ print("\nNew MCP server in your user config:\n "
2812
+ f"{visible(cfg.describe())}")
2813
+ visible.warn()
1588
2814
  answer = _ask("Connect to it? [y/N]: ")
1589
2815
  if answer.strip().lower() in ("y", "yes"):
1590
2816
  mcp_config.remember_server(cfg)
@@ -1594,6 +2820,24 @@ def _confirm_user_level_servers(configs: dict) -> dict:
1594
2820
  return approved
1595
2821
 
1596
2822
 
2823
+ def _ensure_user_mcp_config():
2824
+ """Create the user-level mcp.json when there isn't one. Owner request.
2825
+
2826
+ Returns the path it created, or None. The file is EMPTY -- no example
2827
+ server, no commented-out entry -- because mcp.json is JSON and cannot
2828
+ carry a comment, and a disabled example in a file whose whole purpose
2829
+ is naming a local command to execute is a worse kind of help.
2830
+
2831
+ Here rather than inside setup_mcp() so the created path can become a
2832
+ startup notice: setup_mcp returns the client, and its one except
2833
+ clause reports "setup failed, continuing without MCP", which a file
2834
+ that could not be created is not.
2835
+ """
2836
+ from mcp_client import config as mcp_config
2837
+
2838
+ return mcp_config.ensure_user_config()
2839
+
2840
+
1597
2841
  def setup_mcp(project_path: str):
1598
2842
  """Discover, confirm, connect and register MCP servers (§17).
1599
2843
 
@@ -1625,11 +2869,13 @@ def setup_mcp(project_path: str):
1625
2869
  print(f"[mcp] {len(names)} tool(s) from "
1626
2870
  f"{len(client.clients)} server(s).")
1627
2871
  for name, why in client.failures.items():
1628
- print(f"[mcp] server {name!r} unavailable: {why}", file=sys.stderr)
2872
+ print(f"[mcp] server {name!r} unavailable: "
2873
+ f"{ansi.for_display(why)}", file=sys.stderr)
1629
2874
  return client
1630
2875
  except Exception as e:
1631
2876
  logger.debug("MCP setup failed", exc_info=True)
1632
- print(f"[mcp] setup failed, continuing without MCP: {e}", file=sys.stderr)
2877
+ print("[mcp] setup failed, continuing without MCP: "
2878
+ f"{ansi.for_display(e)}", file=sys.stderr)
1633
2879
  # Returning None here without unwinding is how spawned stdio
1634
2880
  # servers become orphans: teardown_mcp(None) is a no-op, so a
1635
2881
  # failure AFTER connect_all() (registration raising, a partial
@@ -1693,6 +2939,94 @@ def _classify_legacy_threads() -> None:
1693
2939
  connection.close()
1694
2940
 
1695
2941
 
2942
+ def _drop_flag(args: list, flag: str) -> list:
2943
+ """`args` without `flag` and its value, in either spelling.
2944
+
2945
+ argparse accepts `--thread X` and `--thread=X` alike, so a relaunch
2946
+ that handled only the first would pass the old thread AND the new one,
2947
+ and argparse would keep the last -- which happens to be right, and
2948
+ would stop being right the day the order changed.
2949
+ """
2950
+ out, skip = [], False
2951
+ for item in args:
2952
+ if skip:
2953
+ skip = False
2954
+ continue
2955
+ if item == flag:
2956
+ skip = True
2957
+ continue
2958
+ if item.startswith(f"{flag}="):
2959
+ continue
2960
+ out.append(item)
2961
+ return out
2962
+
2963
+
2964
+ def relaunch_argv(request, argv=None) -> list:
2965
+ """The command line that relaunches this harness where it left off.
2966
+
2967
+ THIS LAUNCH'S ARGUMENTS, with three replaced. Everything else is
2968
+ carried verbatim because the user typed it and a restart is not a
2969
+ chance to reinterpret it.
2970
+
2971
+ * `--thread` becomes the conversation that was open, so the restart
2972
+ reopens where it was rather than starting an empty thread beside
2973
+ it. Replaced rather than appended, since this launch may have had
2974
+ one and `/new` or `/resume` may have moved on from it.
2975
+ * `--provider` / `--model` are named only when THIS launch pinned
2976
+ them, which is the fact `request` carries. Unpinned, the
2977
+ remembered pair in tui/preferences.py answers at the next launch
2978
+ exactly as it did at this one, and writing a flag the user never
2979
+ typed would outrank it.
2980
+
2981
+ Pure, and separate from the exec for that reason: what a relaunch
2982
+ should consist of is worth asserting without replacing the test
2983
+ process to find out.
2984
+ """
2985
+ argv = list(sys.argv if argv is None else argv)
2986
+ rest = argv[1:]
2987
+ for flag in ("--thread", "--provider", "--model"):
2988
+ rest = _drop_flag(rest, flag)
2989
+ if request.thread_id:
2990
+ rest += ["--thread", request.thread_id]
2991
+ if request.provider:
2992
+ rest += ["--provider", request.provider]
2993
+ if request.model:
2994
+ rest += ["--model", request.model]
2995
+ return [sys.executable, argv[0], *rest]
2996
+
2997
+
2998
+ def replace_process(command: list) -> int:
2999
+ """Become `command`. Returns only on Windows, and only when it exits.
3000
+
3001
+ POSIX REPLACES THE PROCESS. `execv` keeps the pid, the terminal and
3002
+ the parent's wait, so `bin/venastine.mjs` -- which runs this under
3003
+ `spawnSync` with inherited stdio -- is none the wiser.
3004
+
3005
+ WINDOWS HAS NO EXEC. The C runtime emulates `execv` by starting a new
3006
+ process and exiting, which gives the replacement a DIFFERENT pid: the
3007
+ launcher's wait on this one would return, and the shell prompt would
3008
+ come back over a terminal the replacement is still drawing in. So this
3009
+ process stays, as a waiter around the new one, and passes its exit
3010
+ code up. One extra idle process per restart is the price, and it is
3011
+ the only arrangement that keeps the terminal single-owner.
3012
+
3013
+ The teardown has already run by the time this is called -- see the
3014
+ call site -- so nothing is held open across it either way.
3015
+
3016
+ BATCH 121 NAMES WHAT "SINGLE-OWNER" COSTS ON THIS PATH. The waiter
3017
+ keeps THIS process alive with the console inherited, so anything of
3018
+ ours still reading stdin reads the replacement's keystrokes. The
3019
+ handover before run_tui() is what makes that safe -- it is the same
3020
+ defect as the trust prompt's, one process boundary further along, and
3021
+ it is covered by the same release rather than by a second guard.
3022
+ """
3023
+ if os.name == "nt":
3024
+ import subprocess
3025
+ return subprocess.call(command)
3026
+ os.execv(command[0], command)
3027
+ raise AssertionError("execv returned") # pragma: no cover
3028
+
3029
+
1696
3030
  def main(argv=None) -> int:
1697
3031
  """The CLI, as a function (ROADMAP_v2 §29, N7). Returns an exit code.
1698
3032
 
@@ -1710,6 +3044,17 @@ def main(argv=None) -> int:
1710
3044
  raises it with code 2, and run_research with code 1 on a failed
1711
3045
  pipeline. This returns a code only where it decides one.
1712
3046
  """
3047
+ # ROADMAP_v3 §79 (HD6). FIRST, before anything reads a credential: a
3048
+ # hosted session marks itself non-dumpable, so another visitor's process
3049
+ # in the same container cannot read its memory or environment. Here and
3050
+ # not in the bridge, because an exec resets the flag. And it ends with
3051
+ # the bridge (HD8) rather than outliving it as an orphan.
3052
+ from security import hosted
3053
+
3054
+ if hosted.is_hosted():
3055
+ hosted.make_undumpable()
3056
+ hosted.die_with_parent()
3057
+
1713
3058
  parser = build_parser()
1714
3059
  args = parser.parse_args(argv)
1715
3060
 
@@ -1731,12 +3076,18 @@ def main(argv=None) -> int:
1731
3076
  # behind -- the same argument audit #101 makes one line down.
1732
3077
  # §40 (UN2). ABOVE check_workspace, and that ordering is not
1733
3078
  # cosmetic: the posture is what a later batch lets decide whether the
1734
- # workspace guard runs at all, and `apply_cli` RAISES if anything has
1735
- # already read the posture -- so a reader creeping above this line is
1736
- # a loud startup failure rather than a run that quietly used the
1737
- # config-only value. Below parse_args because the command line feeds
1738
- # it; below configure_logging so the warnings below have somewhere to
1739
- # go.
3079
+ # workspace guard runs at all. Below parse_args because the command
3080
+ # line feeds it; below configure_logging so the warnings below have
3081
+ # somewhere to go.
3082
+ #
3083
+ # THE ORDERING IS NOT ENFORCED AT RUN TIME TODAY (batch 142),
3084
+ # and the sentence that used to be here said it was. `apply_cli` does
3085
+ # raise on a posture CHANGE after a read -- but this call passes no
3086
+ # overrides, so there is no change to detect and a reader creeping
3087
+ # above this line produces nothing at all. What catches it is the
3088
+ # source scan in `test_posture.py`, which covers IMPORT time; a read
3089
+ # placed inside `main()` above this line is covered by neither. Keep
3090
+ # this call here, and keep it FIRST among posture readers.
1740
3091
  posture.apply_cli()
1741
3092
  _announce_posture()
1742
3093
 
@@ -1746,6 +3097,61 @@ def main(argv=None) -> int:
1746
3097
  print(f"[error] {workspace_refusal}", file=sys.stderr)
1747
3098
  return 2
1748
3099
 
3100
+ # THE PROJECT IS THE WORKSPACE WHEN ONE WAS NAMED (batch 44, reversing
3101
+ # RM6). Everything downstream follows from this one line, because
3102
+ # config_loader.get_project_path() is the single resolver: /init's
3103
+ # destination (project_init.generator and, decisively,
3104
+ # write_project_doc's own _project_root), D17 workspace trust, the
3105
+ # `.venastine/` config tier, and UserMemory's project scope (D25/M12).
3106
+ #
3107
+ # RM6 said the opposite -- trust keys off cwd, AGENT_WORKSPACE is a
3108
+ # permission boundary and "deliberately not a project path" -- and the
3109
+ # report that reopened it is what that split actually looks like in
3110
+ # use: with AGENT_WORKSPACE set, read/write/edit/shell were correctly
3111
+ # confined to the project while /init scaffolded documentation into
3112
+ # the HARNESS. One session, two different ideas of where the work was.
3113
+ #
3114
+ # MOVED UP HERE IN BATCH 107, from below create_db_and_tables, so the
3115
+ # refusal underneath it can sit where it has to. Nothing between the
3116
+ # two positions read it; it depends only on config and the cwd.
3117
+ #
3118
+ # UNCHANGED IN BATCH 111, and deliberately: WORKSPACE_DIR_EXPLICIT now
3119
+ # answers to `workspace_is_project` as well as to AGENT_WORKSPACE
3120
+ # (TECHNICAL_DEBT 28), and the whole point of putting the OR inside
3121
+ # config_schema.derived_values is that this line never learns there are
3122
+ # two routes. One question, asked once, answered in the config layer.
3123
+ project_path = (os.path.realpath(config.WORKSPACE_DIR)
3124
+ if config.WORKSPACE_DIR_EXPLICIT else os.getcwd())
3125
+
3126
+ # TECHNICAL_DEBT 26. The other half of the guard six lines up, and it
3127
+ # exists because that one only ever saw a workspace someone NAMED.
3128
+ # With nothing naming one the line above falls back to os.getcwd(),
3129
+ # so launching from the install tree made the harness its own project
3130
+ # -- the same state check_workspace refuses, reached by saying nothing.
3131
+ # Measured from an owner report (batch 96) and reproduced before the
3132
+ # fix (batch 107): the trust prompt listed the harness's own AGENTS.md.
3133
+ #
3134
+ # THIS POSITION IS AS MUCH THE FIX AS THE COMPARISON IS. Above
3135
+ # create_db_and_tables, so a refused launch leaves no database behind
3136
+ # -- audit #101's argument for moving that call, and it applies to the
3137
+ # second refusal exactly as it did to the first. And above
3138
+ # load_project_config, because the reported SYMPTOM is produced inside
3139
+ # it, by _ensure_workspace_trust: a refusal printed after that prompt
3140
+ # would be a refusal after the damage.
3141
+ #
3142
+ # Above the early-exit commands too, so --memories, --forget,
3143
+ # --summary, --init and --secrets are all refused. One rule with no
3144
+ # exceptions (owner decision, batch 107). Four of the five are
3145
+ # project-scoped and refusing them is the point -- --memories here
3146
+ # would list the HARNESS's memories. --secrets is the one that is not,
3147
+ # and it is refused anyway, because a guard with one exception is a
3148
+ # guard someone has to remember.
3149
+ project_refusal = protected_paths.check_project(project_path)
3150
+ if project_refusal:
3151
+ logger.error("%s", project_refusal)
3152
+ print(f"[error] {project_refusal}", file=sys.stderr)
3153
+ return 2
3154
+
1749
3155
  # §29 (N6), audit #101. BELOW parse_args, which is where --help and a
1750
3156
  # typo'd flag exit -- both of which used to create a 77 KB six-table
1751
3157
  # SQLite database and a log directory in whatever directory they were
@@ -1763,27 +3169,12 @@ def main(argv=None) -> int:
1763
3169
  # path can forget to call.
1764
3170
  create_db_and_tables()
1765
3171
 
1766
- # THE PROJECT IS THE WORKSPACE WHEN ONE WAS NAMED (batch 44, reversing
1767
- # RM6). Everything downstream follows from this one line, because
1768
- # config_loader.get_project_path() is the single resolver: /init's
1769
- # destination (project_init.generator and, decisively,
1770
- # write_project_doc's own _project_root), D17 workspace trust, the
1771
- # `.venastine/` config tier, and UserMemory's project scope (D25/M12).
1772
- #
1773
- # RM6 said the opposite -- trust keys off cwd, AGENT_WORKSPACE is a
1774
- # permission boundary and "deliberately not a project path" -- and the
1775
- # report that reopened it is what that split actually looks like in
1776
- # use: with AGENT_WORKSPACE set, read/write/edit/shell were correctly
1777
- # confined to the project while /init scaffolded documentation into
1778
- # the HARNESS. One session, two different ideas of where the work was.
1779
- #
1780
- # SAFE BY AN ORDERING THAT ALREADY EXISTED: check_workspace() ran a
1781
- # few lines above and refuses a workspace that is, or sits inside, the
1782
- # harness install tree. So the project can never become the harness by
1783
- # this route -- and that guard is now load-bearing for a second
1784
- # reason, which is why the launcher must still never set the variable.
1785
- project_path = (os.path.realpath(config.WORKSPACE_DIR)
1786
- if config.WORKSPACE_DIR_EXPLICIT else os.getcwd())
3172
+ # SAFE BY TWO ORDERINGS, ONE OF WHICH ALREADY EXISTED: check_workspace()
3173
+ # refuses a workspace that is, or sits inside, the harness install
3174
+ # tree, and since batch 107 check_project() refuses the implicit route
3175
+ # to the same place. So the project can never become the harness --
3176
+ # and both guards are load-bearing for a second reason, which is why
3177
+ # the launcher must still never set the variable.
1787
3178
  settings = load_project_config(project_path, args.trust_project)
1788
3179
  provider, model = resolve_runtime_defaults(args, settings)
1789
3180
  effort = resolve_effort(args, settings)
@@ -1804,10 +3195,10 @@ def main(argv=None) -> int:
1804
3195
  # named the restored one. The app computes its own against the pair it
1805
3196
  # will actually call. Fixed at the producer: the check was right and
1806
3197
  # its input was wrong.
1807
- if not (args.memories or args.forget or args.tui):
3198
+ if not (args.memories or args.forget or args.secrets or args.tui):
1808
3199
  from credentials import provider_startup_issues
1809
3200
  for warning in provider_startup_issues(provider):
1810
- print(f"[warning] {warning}")
3201
+ print(f"[warning] {ansi.for_display(warning)}")
1811
3202
 
1812
3203
  # §21b M15. AFTER load_project_config, because scoping needs the
1813
3204
  # resolved project path -- and before any MCP setup, since neither
@@ -1815,6 +3206,13 @@ def main(argv=None) -> int:
1815
3206
  if args.memories or args.forget:
1816
3207
  return run_memory_command(args)
1817
3208
 
3209
+ # ROADMAP_v3 §49 slice 5a. Beside the memory commands: no model call,
3210
+ # no MCP server, no thread. ABOVE them in importance only in that it
3211
+ # must run before anything could need a secret, which nothing here
3212
+ # does -- so the ordering is alphabetical rather than load-bearing.
3213
+ if args.secrets:
3214
+ return run_secrets_command(args)
3215
+
1818
3216
  # §21c (M21). Beside the memory commands and for the same reasons: it
1819
3217
  # needs the resolved project path for nothing, but it DOES need the
1820
3218
  # resolved provider/model, and it runs no tool and needs no MCP server.
@@ -1881,7 +3279,42 @@ def main(argv=None) -> int:
1881
3279
  # it reads.
1882
3280
  _classify_legacy_threads()
1883
3281
 
3282
+ # Batch 121. Pre-mount facts a user has to be told, carried rather
3283
+ # than printed: on the TUI path a print here is erased by Textual the
3284
+ # moment it renders (#138), and the non-TUI branch below prints them
3285
+ # to a stdout nothing erases.
3286
+ startup_notices = []
3287
+
3288
+ # The user tier has TWO plausible homes -- the harness root and
3289
+ # ~/.config/venastine -- and nothing in a running session says which
3290
+ # is real, so an edit goes into a file the harness never reads. Owner
3291
+ # request: create the real one, empty, and name it. The skeleton is
3292
+ # §24's own render_mcp(), not a second copy of it.
3293
+ created = _ensure_user_mcp_config()
3294
+ # §79 (batch 168): not in a shared deployment, where the file is in a
3295
+ # session directory deleted with the tab and no tool there can edit it
3296
+ # -- the notice only printed a temporary path at every visitor.
3297
+ if created and not hosted.is_shared():
3298
+ startup_notices.append(
3299
+ f'[mcp] created {created} -- your own MCP servers go in this '
3300
+ f'file, under "mcpServers". Project servers stay in '
3301
+ f'.venastine/mcp.json, where the trust prompt covers them.')
3302
+
1884
3303
  mcp = setup_mcp(project_path)
3304
+ # Batch 84. Set only by a `/config` write the user chose to apply. The
3305
+ # relaunch happens AFTER the teardown below, never from inside the TUI:
3306
+ # the MCP servers are subprocesses of this one and the database is open,
3307
+ # and a process replaced from in there would never reach that `finally`.
3308
+ restart = None
3309
+ if not args.tui:
3310
+ for line in startup_notices:
3311
+ print(line)
3312
+ # The CLI shells print to a stdout nothing erases, so the launcher's
3313
+ # own print of the config merge report already reached the user on
3314
+ # this path. Marking it seen here stops a later TUI session replaying
3315
+ # a report they have read; the TUI branch below marks it at mount
3316
+ # instead, after writing it into the transcript where it survives.
3317
+ config_update.mark_report_seen()
1885
3318
  try:
1886
3319
  if args.tui:
1887
3320
  # Detach the stderr handler before Textual takes the screen.
@@ -1909,9 +3342,30 @@ def main(argv=None) -> int:
1909
3342
  # apply. Computed from args rather than by comparing the
1910
3343
  # resolved pair against settings.json, which would read a
1911
3344
  # flag that happens to match the configured value as absent.
1912
- run_tui(provider, model, settings,
1913
- cli_pinned=args.provider is not None
1914
- or args.model is not None)
3345
+ # BATCH 121, AND IT MUST BE THE LAST THING BEFORE THE APP.
3346
+ # Textual reads this console from its own thread
3347
+ # (win32.EventMonitor, or the selector on POSIX), so a reader
3348
+ # left parked here is a SECOND reader on one terminal and the
3349
+ # parked read wins: measured, an EventMonitor-shaped loop saw
3350
+ # 0 of 5 injected characters with the trust prompt's pump
3351
+ # alive and 5 of 5 without it. That is the owner's report --
3352
+ # a UI that animates and ignores the keyboard, Ctrl included,
3353
+ # because `enable_application_mode` clears
3354
+ # ENABLE_PROCESSED_INPUT and Ctrl+C is just another key event
3355
+ # in the queue the wrong reader is draining.
3356
+ #
3357
+ # Nothing can refuse today -- both pre-TUI prompts go through
3358
+ # readline(), which starts no pump -- and the warning exists
3359
+ # because the alternative symptom is silence.
3360
+ if not _release_terminal():
3361
+ startup_notices.append(
3362
+ "[warning] something else is still reading this "
3363
+ "terminal, so keyboard input may be lost. Restart "
3364
+ "the harness in a fresh terminal.")
3365
+ restart = run_tui(provider, model, settings,
3366
+ cli_pinned=args.provider is not None
3367
+ or args.model is not None,
3368
+ startup_notices=startup_notices)
1915
3369
  elif args.mode == "research":
1916
3370
  # AFTER setup_mcp: the tools a grant can cover are named at
1917
3371
  # connection time, so asking any earlier would offer a list
@@ -1950,10 +3404,30 @@ def main(argv=None) -> int:
1950
3404
  # finally, not "at the end": run_research raises SystemExit(1) on a
1951
3405
  # failed pipeline, and Ctrl+C reaches here as KeyboardInterrupt.
1952
3406
  # Both are ordinary exits that must still reap child processes.
3407
+ #
3408
+ # ROADMAP_v3 §49 (SS6). Sessions first: killing them writes a row
3409
+ # into each owning thread saying what became of them, and that
3410
+ # write needs the database this process has not closed yet.
3411
+ _close_sessions()
1953
3412
  from tools.registry import registry
1954
3413
  teardown_mcp(mcp, registry)
3414
+ if isinstance(restart, config_edit.RestartRequest):
3415
+ # Everything this process held is closed. `replace_process` does
3416
+ # not return on POSIX.
3417
+ print(f"[restarting to apply {restart.key}]")
3418
+ return replace_process(relaunch_argv(restart))
1955
3419
  return 0
1956
3420
 
1957
3421
 
1958
3422
  if __name__ == "__main__":
1959
- raise SystemExit(main())
3423
+ try:
3424
+ raise SystemExit(main())
3425
+ except KeyboardInterrupt:
3426
+ # THE WINDOWS RESTART WAITER NEEDS THIS. `replace_process` keeps this
3427
+ # process alive around `subprocess.call` because Windows has no exec,
3428
+ # and the console delivers CTRL_C_EVENT to every process attached to
3429
+ # it -- so a Ctrl+C aimed at the RELAUNCHED TUI also lands here, and
3430
+ # an unhandled one prints a traceback over the child's live screen.
3431
+ # `bin/venastine.mjs` ignores SIGINT for the same reason, in its own
3432
+ # words: let the child own the terminal's interrupt.
3433
+ raise SystemExit(130) from None