fix: #163 — remove [turn N] suffix pollution from run_turn_loop; file #164 timeout-cancellation followup

#163: run_turn_loop no longer injects f'{prompt} [turn N]' into follow-up
prompts. The suffix was never defined or interpreted anywhere — not by the
engine, not by the system prompt, not by any LLM. It looked like a real
user-typed annotation in the transcript and made replay/analysis fragile.

New behaviour:
- turn 0 submits the original prompt (unchanged)
- turn > 0 submits caller-supplied continuation_prompt if provided, else
  the loop stops cleanly — no fabricated user turn
- added continuation_prompt: str | None = None parameter to run_turn_loop
- added --continuation-prompt CLI flag for claws scripting multi-turn loops
- zero '[turn' strings ever appear in mutable_messages or stdout now

Behaviour change for existing callers:
- Before: run_turn_loop(prompt, max_turns=3) submitted 3 turns
  ('prompt', 'prompt [turn 2]', 'prompt [turn 3]')
- After:  run_turn_loop(prompt, max_turns=3) submits 1 turn ('prompt')
- To preserve old multi-turn behaviour, pass continuation_prompt='Continue.'
  or any structured follow-up text

One existing timeout test (test_budget_is_cumulative_across_turns) updated
to pass continuation_prompt so the cumulative-budget contract is actually
exercised across turns instead of trivially satisfied by a one-turn loop.

#164 filed: addresses reviewer feedback on #161. The wall-clock timeout
bounds the caller-facing wait, but the underlying submit_message worker
thread keeps running and can mutate engine state after the timeout
TurnResult is returned. A cooperative cancel_event pattern is sketched in
the pinpoint; real asyncio.Task.cancel() support will come once provider
IO is async-native (larger refactor).

Tests (tests/test_run_turn_loop_continuation.py, 8 tests):
- TestNoTurnSuffixInjection (2): zero '[turn' strings in any submitted
  prompt, both default and explicit-continuation paths
- TestContinuationDefaultStopsAfterTurnZero (2): default loops run exactly
  one turn; engine.submit_message called exactly once despite max_turns=10
- TestExplicitContinuationBehaviour (2): turn 0 = original, turn N = continuation
  verbatim; max_turns still respected
- TestCLIContinuationFlag (2): CLI default emits only '## Turn 1';
  --continuation-prompt wires through to multi-turn behaviour

Full suite: 67/67 passing.

Closes ROADMAP #163. Files #164.

src/main.py

@@ -71,6 +71,15 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help='total wall-clock budget across all turns (#161). Default: unbounded.',
     )
+    loop_parser.add_argument(
+        '--continuation-prompt',
+        default=None,
+        help=(
+            'prompt to submit on turns after the first (#163). Default: None '
+            '(loop stops after turn 0). Replaces the deprecated implicit "[turn N]" '
+            'suffix that used to pollute the transcript.'
+        ),
+    )
 
     flush_parser = subparsers.add_parser('flush-transcript', help='persist and flush a temporary session transcript')
     flush_parser.add_argument('prompt')
@@ -199,6 +208,7 @@ def main(argv: list[str] | None = None) -> int:
             max_turns=args.max_turns,
             structured_output=args.structured_output,
             timeout_seconds=args.timeout_seconds,
+            continuation_prompt=args.continuation_prompt,
         )
         for idx, result in enumerate(results, start=1):
             print(f'## Turn {idx}')

src/runtime.py

@@ -160,6 +160,7 @@ class PortRuntime:
         max_turns: int = 3,
         structured_output: bool = False,
         timeout_seconds: float | None = None,
+        continuation_prompt: str | None = None,
     ) -> list[TurnResult]:
         """Run a multi-turn engine loop with optional wall-clock deadline.
 
@@ -172,6 +173,15 @@ class PortRuntime:
                 budget is exhausted mid-turn, a synthetic TurnResult with
                 ``stop_reason='timeout'`` is appended and the loop exits.
                 ``None`` (default) preserves legacy unbounded behaviour.
+            continuation_prompt: What to send on turns after the first. When
+                ``None`` (default, #163), the loop stops after turn 0 and the
+                caller decides how to continue. When set, the same text is
+                submitted for every turn after the first, giving claws a clean
+                hook for structured follow-ups (e.g. ``"Continue."``, a
+                routing-planner instruction, or a tool-output cue). Previously
+                the loop silently appended ``" [turn N]"`` to the original
+                prompt, polluting the transcript with harness-generated
+                annotation the model had no way to interpret.
 
         Returns:
             A list of TurnResult objects. The final entry's ``stop_reason``
@@ -182,6 +192,12 @@ class PortRuntime:
         block the loop indefinitely with no cancellation path, forcing claws to
         rely on external watchdogs or OS-level kills. Callers can now enforce a
         deadline and receive a typed timeout signal instead.
+
+        #163: the old ``f'{prompt} [turn {turn + 1}]'`` suffix was never
+        interpreted by the engine or any system prompt. It looked like a real
+        user turn in ``mutable_messages`` and the transcript, making replay and
+        analysis fragile. Removed entirely; callers supply ``continuation_prompt``
+        for meaningful follow-ups or let the loop stop after turn 0.
         """
         engine = QueryEnginePort.from_workspace()
         engine.config = QueryEngineConfig(max_turns=max_turns, structured_output=structured_output)
@@ -195,7 +211,17 @@ class PortRuntime:
         executor = ThreadPoolExecutor(max_workers=1) if deadline is not None else None
         try:
             for turn in range(max_turns):
-                turn_prompt = prompt if turn == 0 else f'{prompt} [turn {turn + 1}]'
+                # #163: no more f'{prompt} [turn N]' suffix injection.
+                # On turn 0 submit the original prompt.
+                # On turn > 0, submit the caller-supplied continuation prompt;
+                # if the caller did not supply one, stop the loop cleanly instead
+                # of fabricating a fake user turn.
+                if turn == 0:
+                    turn_prompt = prompt
+                elif continuation_prompt is not None:
+                    turn_prompt = continuation_prompt
+                else:
+                    break
 
                 if deadline is None:
                     # Legacy path: unbounded call, preserves existing behaviour exactly.