slipwai 1.2.0.dev44__tar.gz → 1.2.0.dev46__tar.gz

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: slipwai
-Version: 1.2.0.dev44
+Version: 1.2.0.dev46
 Summary: One-shot scaffolder for product monorepos: a walking skeleton, a verify gate, a path to production, and a repository set up for coding agents.
 Project-URL: Homepage, https://github.com/ROBCOATVG/slipwai
 Project-URL: Repository, https://git.treyco.dev/ROBCOATVG/slipwai
@@ -274,6 +274,7 @@ the paths and toolchains named in them are real.
 | `/cruise-settings` | Shows or changes how `/cruise` runs: who decides, how it releases, what it demos with, when it parks |
 | `/cruise-status` | Says whether a `/cruise` runner is running, how its last iteration ended, and shows the tail of its feed |
 | `/cruise-stop` | Ends a `/cruise` run after the iteration in flight, or at once with `now` |
+| `/cruise-tell` | Queues a message for a running `/cruise`, which the next iteration carries; `--now` ends the iteration in flight for it |
 
 [The delivery loop](docs/delivery-loop.md) describes each one in full, and the ladder they sit on.
 

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/README.md

@@ -245,6 +245,7 @@ the paths and toolchains named in them are real.
 | `/cruise-settings` | Shows or changes how `/cruise` runs: who decides, how it releases, what it demos with, when it parks |
 | `/cruise-status` | Says whether a `/cruise` runner is running, how its last iteration ended, and shows the tail of its feed |
 | `/cruise-stop` | Ends a `/cruise` run after the iteration in flight, or at once with `now` |
+| `/cruise-tell` | Queues a message for a running `/cruise`, which the next iteration carries; `--now` ends the iteration in flight for it |
 
 [The delivery loop](docs/delivery-loop.md) describes each one in full, and the ladder they sit on.
 

slipwai-1.2.0.dev46/VERSION

@@ -0,0 +1 @@
+1.2.0.dev46

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/assets/toolkit/scripts/agents/cruise.py

@@ -16,6 +16,8 @@ with `start`, and the session that typed it runs no stage of the ladder.
     python3 scripts/agents/cruise.py start [--feature F] [--no-park] [--sandbox] [kick-off…] # the loop, detached
     python3 scripts/agents/cruise.py watch [--minutes M] [--quiet S]  # the watch seat: the feed since the last watch
     python3 scripts/agents/cruise.py stop [--now]  # end the run after the iteration in flight, or now
+    python3 scripts/agents/cruise.py tell [--now] <message…>  # queue a message for the next iteration; --now ends the one in flight
+    python3 scripts/agents/cruise.py told        # inside an iteration: what a person queued since it started, or nothing
     python3 scripts/agents/cruise.py status      # whether a runner is running, and what the log says it is doing
     python3 scripts/agents/cruise.py denials     # every command an iteration was refused, from the stream: what to allow
     python3 scripts/agents/cruise.py resume      # print the checkpoint into a compacted context; nothing when none
@@ -40,7 +42,11 @@ harness.
 
 A person stops a run with `touch .specify/cruise.stop` (`stop`), or by interrupting a foreground `run`: the
 iteration under way is killed, its increment commits are on the slice branch, and the next iteration re-derives
-from disk.
+from disk. A person steers a run with `tell`: the message is queued in `.specify/cruise-inbox.jsonl`, and the
+next iteration carries it as `told: <message>` in its argument — the route the kick-off takes — so nothing
+interrupts the iteration in flight unless `--now` says to, which ends that iteration the way `stop --now` does
+and starts the next at once with the message. An iteration can also ask for what was queued since it started
+(`told`), between stages, without waiting for its end. Every message delivered is in the iteration's log entry.
 """
 
 from __future__ import annotations
@@ -94,6 +100,11 @@ MCP_CONFIG = ROOT / ".mcp.json"
 WATCH_CURSOR = ROOT / ".specify/cruise-watch.cursor"
 # The last message a harness's after-response hook saw, for a stop hook whose event does not carry it.
 LAST_RESPONSE = ROOT / ".specify/cruise-last-response.txt"
+# What a person queued for the run (`tell`), one JSON line per message, until an iteration takes it: the runner
+# before it starts one, or the iteration itself between stages (`told`). What was taken waits in the second file
+# until the runner writes the iteration's log entry, so every message delivered is on the record whichever took it.
+INBOX = ROOT / ".specify/cruise-inbox.jsonl"
+TOLD = ROOT / ".specify/cruise-told.jsonl"
 LOG = ROOT / "specs/cruise-log.jsonl"
 # The iteration in flight, rewritten by `/cruise` at every stage boundary so a compacted context can resume.
 CHECKPOINT = ROOT / "specs/cruise-checkpoint.md"
@@ -168,6 +179,11 @@ ABSENT = f"no {CONFIG.relative_to(ROOT)}: /cruise is not enabled here; `slipwai
 PARENT_SESSION_VARIABLES = ("CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT")
 # The iteration under way, so a SIGTERM to the runner ends it too rather than orphaning a harness session.
 CURRENT: subprocess.Popen[str] | None = None
+# Set by the SIGUSR1 handler (`tell --now`) while an iteration was under way: it was ended for a person's message,
+# which the runner says in its log entry instead of reading its missing last line as no progress.
+INTERRUPTED = False
+# The word an iteration's argument carries a person's message under, beside `unblock:`, as `commands/cruise.md` spells it.
+TOLD_WORD = "told:"
 
 
 def now() -> str:
@@ -432,7 +448,7 @@ def fingerprint() -> str:
     status = subprocess.run(["git", "status", "--porcelain", "--untracked-files=all"], cwd=ROOT, text=True,
                             capture_output=True)
     own = tuple(path.relative_to(ROOT).as_posix()
-                for path in (LOG, CHECKPOINT, PID, RUN_LOG, STREAM, WATCH_CURSOR, LAST_RESPONSE))
+                for path in (LOG, CHECKPOINT, PID, RUN_LOG, STREAM, WATCH_CURSOR, LAST_RESPONSE, INBOX, TOLD))
     digest.update("\n".join(line for line in status.stdout.splitlines() if not line.endswith(own)).encode())
     specs = ROOT / "specs"
     for path in sorted(specs.rglob("*")) if specs.is_dir() else []:
@@ -678,15 +694,17 @@ def iterate(template: str, prompt: str, environment: dict[str, str], iteration:
             raw.close()
     # What the session left running — the app its demo started, which the ladder leaves up for a person who
     # is not coming, a watcher — is ended with the iteration, or the next one finds the port taken. The group
-    # outlives its leader while any member does, so a signal that lands is the sign something was left.
+    # outlives its leader while any member does, so a signal that lands is the sign something was left — unless
+    # the group was ended for a person's message, in which case whatever is still dying was ended on purpose.
     try:
         os.killpg(process.pid, signal.SIGTERM)
     except ProcessLookupError:
         pass
     else:
-        sys.stdout.write(f"{time.strftime('%H:%M:%S')}  cruise: iteration {iteration} left a process running — "
-                         "a dev server, a watcher — and it was ended with the iteration\n")
-        sys.stdout.flush()
+        if not INTERRUPTED:
+            sys.stdout.write(f"{time.strftime('%H:%M:%S')}  cruise: iteration {iteration} left a process running — "
+                             "a dev server, a watcher — and it was ended with the iteration\n")
+            sys.stdout.flush()
     return feed.last
 
 
@@ -829,17 +847,26 @@ def stopping() -> None:
 
 
 def park(reason: str, no_park: bool, poll: float, seen: str) -> None:
-    """Wait for a person: the stop file ends the run, a change under specs/ resumes it, `--no-park` exits 3."""
+    """Wait for a person: the stop file ends the run, a change under specs/ or a message resumes it, `--no-park`
+    exits 3. The tree is re-read every poll; the stop file and the inbox every second, because a person who typed
+    something into a parked run is waiting for it and `poll_minutes` is sized for a tree nobody is touching."""
     print(f"cruise: parked — {reason}")
     if no_park:
         raise SystemExit(PARKED_EXIT)
-    print(f"cruise: waiting; `touch {relative(STOP)}` ends the run, a change under specs/ or a commit "
-          "resumes it", flush=True)
+    print(f"cruise: waiting; `touch {relative(STOP)}` ends the run, a change under specs/, a commit or a message "
+          "(`python3 scripts/agents/cruise.py tell …`) resumes it", flush=True)
     while True:
-        time.sleep(poll)
-        if STOP.is_file():
-            print("cruise: stopped by human")
-            raise SystemExit(0)
+        slept = 0.0
+        while slept < poll:
+            step = min(1.0, poll - slept)
+            time.sleep(step)
+            slept += step
+            if STOP.is_file():
+                print("cruise: stopped by human")
+                raise SystemExit(0)
+            if INBOX.is_file():
+                print("cruise: a person's message; resuming")
+                return
         if fingerprint() != seen:
             print("cruise: something changed; resuming")
             return
@@ -875,6 +902,124 @@ def terminated(_signal: int, _frame: object) -> None:
     raise SystemExit(128 + signal.SIGTERM)
 
 
+def interrupted(_signal: int, _frame: object) -> None:
+    """A SIGUSR1 to the runner (`tell --now`) ends the iteration under way for a person's message, and nothing
+    else: the loop goes on, and the next iteration starts at once with the inbox as its argument. Between
+    iterations, or parked, there is nothing to end, and the inbox is read within the second anyway."""
+    global INTERRUPTED
+    if CURRENT is not None and CURRENT.poll() is None:
+        INTERRUPTED = True
+        try:
+            os.killpg(CURRENT.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+
+
+def queued() -> list[dict[str, Any]]:
+    """What a person has queued and no iteration has taken yet, oldest first."""
+    if not INBOX.is_file():
+        return []
+    return [json.loads(line) for line in INBOX.read_text().splitlines() if line.strip()]
+
+
+def deliver() -> list[str]:
+    """Take everything queued, in order, and keep it for the iteration's log entry. The file is moved before it
+    is read, so a `tell` landing at this moment goes to a fresh inbox rather than being lost."""
+    if not INBOX.is_file():
+        return []
+    taken = INBOX.with_suffix(".taking")
+    try:
+        os.replace(INBOX, taken)
+    except FileNotFoundError:
+        return []
+    lines = [line for line in taken.read_text().splitlines() if line.strip()]
+    taken.unlink()
+    with TOLD.open("a") as handle:
+        handle.write("".join(f"{line}\n" for line in lines))
+    return [str(json.loads(line)["text"]) for line in lines]
+
+
+def delivered() -> list[dict[str, Any]]:
+    """Every message an iteration was given, by the runner or by `told`, and the file cleared for the next."""
+    if not TOLD.is_file():
+        return []
+    given = [json.loads(line) for line in TOLD.read_text().splitlines() if line.strip()]
+    TOLD.unlink()
+    return given
+
+
+def requeue(given: list[dict[str, Any]]) -> None:
+    """Put back, ahead of anything queued since, what an iteration was given and never got to act on — one
+    ended for a later message, or a run ended under it. A person's word is not spent by an iteration that died."""
+    if not given:
+        return
+    lines = [json.dumps(entry, ensure_ascii=False) for entry in given] + [
+        json.dumps(entry, ensure_ascii=False) for entry in queued()]
+    INBOX.parent.mkdir(parents=True, exist_ok=True)
+    INBOX.write_text("".join(f"{line}\n" for line in lines))
+
+
+def told_argument(texts: list[str]) -> str:
+    """The messages as an iteration's argument: `told: <one>`, or the several in order, each on its own `told:`."""
+    return " ".join(f"{TOLD_WORD} {' '.join(text.split())}" for text in texts)
+
+
+def tell(arguments: list[str]) -> None:
+    """Queue a message for the run: the next iteration carries it as `told: <message>` in its argument. With
+    `--now` — the first word, on the command line or in the text — the iteration in flight is ended for it and
+    the next starts at once. The message is the words given, or standard input when there are none, so a
+    command file can hand it over in a quoted heredoc and no quote inside it reaches the shell."""
+    # A bare `tell` at a terminal is a person who forgot the message, not one about to type it into a pipe.
+    text = " ".join(arguments).strip() if arguments else ("" if sys.stdin.isatty() else sys.stdin.read().strip())
+    now_flag = False
+    if text == "--now" or text.startswith("--now "):
+        now_flag, text = True, text.removeprefix("--now").strip()
+    if not text:
+        raise RuntimeError("tell takes the message as its words, or on standard input")
+    INBOX.parent.mkdir(parents=True, exist_ok=True)
+    with INBOX.open("a") as handle:
+        handle.write(json.dumps({"at": now(), "text": text, "now": now_flag}, ensure_ascii=False) + "\n")
+    waiting = len(queued())
+    count = f"{waiting} message(s) queued" if waiting > 1 else "queued"
+    running = running_pid()
+    if running is None:
+        print(f"cruise: {count}; no runner is running here — the first iteration of the next run carries it "
+              "(`/cruise` starts one)")
+        return
+    # A parked runner says so as the last line of its log; a foreground one prints it instead, so there the log
+    # entry is the evidence, and it cannot say whether something resumed the run since.
+    tail = RUN_LOG.read_text(errors="replace").rstrip().splitlines()[-1:] if RUN_LOG.is_file() else []
+    log = entries()
+    if tail and tail[-1].startswith("cruise: waiting;"):
+        print(f"cruise: {count}; the run is parked and resumes with it within the second")
+        return
+    if not tail and log and str(log[-1]["last_line"]).startswith("cruise: parked: "):
+        print(f"cruise: {count}; the run parked after iteration {log[-1]['iteration']} and resumes with it within "
+              "the second — unless something already resumed it, in which case the next iteration carries it")
+        return
+    if now_flag:
+        os.kill(running[0], signal.SIGUSR1)
+        print(f"cruise: {count}, and the runner (pid {running[0]}) was told to end the iteration in flight for it; "
+              "the next iteration starts at once with the message, and the ended iteration's increment commits "
+              "are on its branch")
+        return
+    print(f"cruise: {count} for the next iteration; the one in flight ends first — the runner (pid {running[0]}) "
+          "reads the inbox before each iteration, and the iteration itself between stages. "
+          "`python3 scripts/agents/cruise.py tell --now …` would end the one in flight for it")
+
+
+def told() -> None:
+    """Inside an iteration, between stages: what a person queued since the iteration started, one line each,
+    taken — so the next iteration is not given it again — and kept for this iteration's log entry."""
+    texts = deliver()
+    if not texts:
+        return
+    print(f"cruise: {len(texts)} message(s) from a person since this iteration started; act on each before the "
+          "next stage, and write down what must outlive this iteration")
+    for text in texts:
+        print(f"cruise: {TOLD_WORD} {text}")
+
+
 def cut_off_brackets(reason: str) -> None:
     """Close what the iteration's session left open in the benchmark records: nothing will `end` it now, and an
     entry left open reads as a stage still running (`scripts/agents/benchmark.py cut-off`). Its lines go to the
@@ -917,9 +1062,12 @@ def run(arguments: list[str]) -> None:
     first = prompt_for(harness, " ".join(part for part in (feature, kickoff) if part))
     PID.parent.mkdir(parents=True, exist_ok=True)
     PID.write_text(f"{os.getpid()} {now()}\n")
+    # What a run that ended under an iteration — `stop --now`, a killed runner — had given it is not spent.
+    requeue(delivered())
     signal.signal(signal.SIGTERM, terminated)
+    signal.signal(signal.SIGUSR1, interrupted)
     try:
-        drive(table, harness, template, why, environment, prompt, first, feature, no_park)
+        drive(table, harness, template, why, environment, prompt, first, feature, kickoff, no_park)
     finally:
         if PID.is_file() and PID.read_text().split()[:1] == [str(os.getpid())]:
             PID.unlink()
@@ -937,7 +1085,8 @@ def settings_now(table: dict[str, Any]) -> dict[str, Any]:
 
 
 def drive(table: dict[str, Any], harness: dict[str, Any] | None, template: str, why: str,
-          environment: dict[str, str], prompt: str, first: str, feature: str | None, no_park: bool) -> None:
+          environment: dict[str, str], prompt: str, first: str, feature: str | None, kickoff: str | None,
+          no_park: bool) -> None:
     print(f"cruise: {why}")
     if first != prompt:
         print(f"cruise: the first iteration runs `{first}`, the kick-off; every later one runs `{prompt}`")
@@ -948,10 +1097,12 @@ def drive(table: dict[str, Any], harness: dict[str, Any] | None, template: str,
     stream = stream_of(harness)
     started_run = time.monotonic()
     iterations_this_run = 0
-    fingerprints = [entry["fingerprint"] for entry in entries()]
+    # An iteration a person ended for a message is not the run failing to move, so it is not in the stuck window.
+    fingerprints = [entry["fingerprint"] for entry in entries() if not entry.get("interrupted")]
     # The fingerprint a stuck run was already given its one unblocking iteration at, so it gets exactly one.
     unblocked_at: str | None = None
     ask, attempt = first, "kick-off" if first != prompt else None
+    global INTERRUPTED
     while True:
         table = settings_now(table)
         poll = float(os.environ.get("CRUISE_POLL_SECONDS", table["poll_minutes"] * 60))
@@ -968,27 +1119,55 @@ def drive(table: dict[str, Any], harness: dict[str, Any] | None, template: str,
         if table["max_hours"] is not None and time.monotonic() - started_run >= table["max_hours"] * 3600:
             print(f"cruise: budget spent — {table['max_hours']} hour(s)")
             return
+        # A person's message rides on this iteration's argument: after the kick-off on the first, in place of
+        # the bosun's `unblock:` — a person's word is the likelier thing to move a stuck run, and the bosun's one
+        # iteration is kept for after it — and alone on any other.
+        messages = deliver()
+        if messages:
+            if attempt == "unblock":
+                unblocked_at, attempt = None, None
+            ask = prompt_for(harness, " ".join(part for part in (
+                feature, kickoff if attempt == "kick-off" else None, told_argument(messages)) if part))
+            print(f"cruise: iteration {len(entries()) + 1} carries {len(messages)} message(s) from a person", flush=True)
         iteration = len(entries()) + 1
         started = now()
         LAST_RESPONSE.unlink(missing_ok=True)
+        INTERRUPTED = False
         print(f"cruise: iteration {iteration} started {started}, running `{ask}`", flush=True)
         began = time.monotonic()
         # The model flag is read with the settings, so `/cruise-settings model=…` holds from the next iteration.
         last = iterate(template + model_flags(harness, table["model"]), ask, environment, iteration, stream)
-        cut_off_brackets(f"iteration {iteration} ended with the entry open")
+        if INTERRUPTED:
+            last = "interrupted: a person's message"
+            cut_off_brackets("the iteration was ended by `tell --now`")
+        else:
+            cut_off_brackets(f"iteration {iteration} ended with the entry open")
         iterations_this_run += 1
         seen = fingerprint()
-        fingerprints.append(seen)
+        if not INTERRUPTED:
+            fingerprints.append(seen)
         entry: dict[str, Any] = {"iteration": iteration, "started": started, "ended": now(),
                                  "harness": harness["key"] if harness is not None else "override",
                                  "last_line": last or "no last line", "fingerprint": seen}
         if attempt is not None:
             entry["attempt"] = attempt
+        given = delivered()
+        if given:
+            entry["told"] = [str(each["text"]) for each in given]
+        if INTERRUPTED:
+            # The entry says what the iteration was given; the next is given it again, ahead of the message that
+            # ended this one, since nothing says this one acted on it.
+            entry["interrupted"] = True
+            requeue(given)
         ask, attempt = prompt, None
         record(entry)
         # The boundary `watch` returns on: the iteration, what it ended on, and how long it took.
         print(f"cruise: iteration {iteration} ended — {last or 'no last line'} ({duration(time.monotonic() - began)})",
               flush=True)
+        if INTERRUPTED:
+            # Ended for a message, not by its own last line: the next iteration is where the message goes, and it
+            # starts now — there is nothing to park on and nothing to count.
+            continue
         if last in ("cruise: done", "cruise: stopped: human"):
             # The iteration is over for good; a checkpoint left behind would read as state to resume.
             CHECKPOINT.unlink(missing_ok=True)
@@ -1036,7 +1215,7 @@ def start(arguments: list[str]) -> None:
     first = prompt_for(harness, " ".join(part for part in (feature, kickoff) if part))
     # Said before the fork, so a runner that ends at once has still said what its iterations run on and how they
     # reach the index.
-    for line in model_lines(harness, table["model"]) + index_lines(harness):
+    for line in model_lines(harness, table["model"]) + index_lines(harness) + queued_lines():
         print(line)
     RUN_LOG.parent.mkdir(parents=True, exist_ok=True)
     # The watch seat starts reading here, so the first `watch` shows this run from its first line.
@@ -1302,12 +1481,25 @@ def denials() -> None:
               f"{', '.join(str(each) for each in where)})")
 
 
+def queued_lines() -> list[str]:
+    """What `status` and `start` say of the inbox: each message waiting for the next iteration, or nothing."""
+    waiting = queued()
+    if not waiting:
+        return []
+    return [f"cruise: {len(waiting)} message(s) queued for the next iteration ({relative(INBOX)}):"] + [
+        f"cruise:   {first_line(entry['text'])}" + (" (asked to end the iteration in flight)" if entry.get("now") else "")
+        for entry in waiting
+    ]
+
+
 def status() -> None:
     running = running_pid()
     if running is not None:
         print(f"cruise: the runner is running (pid {running[0]}, since {running[1]}); its log is {relative(RUN_LOG)}")
     else:
         print("cruise: no runner is running here")
+    for line in queued_lines():
+        print(line)
     log = entries()
     if not log:
         print("cruise: no iteration has run here")
@@ -1339,6 +1531,7 @@ def main() -> None:
         return
     verbs = {"run": lambda: run(arguments[1:]), "start": lambda: start(arguments[1:]),
              "watch": lambda: watch(arguments[1:]), "stop": lambda: stop(arguments[1:]), "status": status,
+             "tell": lambda: tell(arguments[1:]), "told": told,
              "denials": denials, "resume": resume, "compacting": compacting, "loop": loop, "stopping": stopping,
              "responded": responded}
     if arguments and arguments[0] in verbs:

slipwai-1.2.0.dev46/changelog.d/cruise-tell.md

@@ -0,0 +1,18 @@
+MINOR
+
+**A person can tell a running `/cruise` something without stopping it.** `/cruise-tell <message>` in any
+session, `make cruise-tell MSG="…"`, or `python3 scripts/agents/cruise.py tell …` queues the message in
+`.specify/cruise-inbox.jsonl`; the runner reads the inbox before it starts each iteration and hands the message
+over as `told: <message>` in that iteration's argument — the route the kick-off takes — and the command reads it
+before the first stage and acts on it first, writing what must outlive the iteration into the owner brief or a
+decision entry. Between stages an iteration runs `python3 scripts/agents/cruise.py told` for what was queued since
+it started, so a message can land mid-iteration without cutting a stage. A parked run resumes with a message
+within the second, and a message waiting when a run is stuck goes in place of the bosun's `unblock:` iteration.
+`--now` as the first word ends the iteration in flight for the message, the way `stop --now` does, and starts the
+next at once; the log entry says so, and an interrupted iteration is not counted by the stuck detector. Every
+message delivered is in that iteration's entry in `specs/cruise-log.jsonl` under `told`, and `/cruise-status` lists
+what is queued. The watch seat queues what a person types for the run the same way and repeats what the script
+said. Every setting keeps its meaning; a message never changes one.
+
+**Catch-up.** `slipwai migrate` brings the runner, the command files and the Make target; the inbox and the
+delivered file are gitignored.

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/src/slipwai/project/agent_targets.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 def agent_targets() -> str:
     """The `.PHONY` block between the npm workspace targets and the native gate targets."""
-    return """.PHONY: agents agents-list check-extensions check-agents models check-benchmark benchmark cruise cruise-watch cruise-status cruise-stop check-decisions
+    return """.PHONY: agents agents-list check-extensions check-agents models check-benchmark benchmark cruise cruise-watch cruise-status cruise-stop cruise-tell check-decisions
 agents: ## Refresh elected extensions, then skills, commands and agent types in every installed agent harness
 \tpython3 scripts/extensions/project.py
 \tpython3 scripts/agents/project.py
@@ -37,6 +37,8 @@ cruise-status: ## Say whether a /cruise runner is running and what its log shows
 \tpython3 scripts/agents/cruise.py status
 cruise-stop: ## End a /cruise run after the iteration in flight (CRUISE_FLAGS=--now ends that iteration too)
 \tpython3 scripts/agents/cruise.py stop $(CRUISE_FLAGS)
+cruise-tell: ## Queue a message for the next /cruise iteration (MSG=\"…\"; CRUISE_FLAGS=--now ends the iteration in flight so it goes at once)
+\tpython3 scripts/agents/cruise.py tell $(CRUISE_FLAGS) $(MSG)
 check-decisions: ## Fail when a decision log or demo log /cruise wrote has lost its shape
 \tpython3 scripts/check-decisions.py
 """

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/src/slipwai/project/commands.py

@@ -11,7 +11,7 @@ from .adversary import adversary_command
 from .benchmark import benchmark_command, what_each_stage_costs
 from .converge_stage import convergence_stage
 from .cruise import cruise_command, cruise_settings_command
-from .cruise_seat import cruise_status_command, cruise_stop_command
+from .cruise_seat import cruise_status_command, cruise_stop_command, cruise_tell_command
 from .demo_stop import demo_stop
 from .drive_adoption import adoption_ladder
 from .drive_settings import drive_settings_command, implementation_section
@@ -310,7 +310,7 @@ than an open question.
 # three reaching back out to the factory. One list, so the documentation and the files cannot disagree.
 BASE_COMMANDS = ("drive", "where-are-we", "whats-next", "gaps", "adversary", "mutation", "constitution-coverage",
                  "model-delegation-settings", "drive-settings", "benchmark", "cruise", "cruise-settings",
-                 "cruise-status", "cruise-stop", "add-service", "add-frontend", "catch-up")
+                 "cruise-status", "cruise-stop", "cruise-tell", "add-service", "add-frontend", "catch-up")
 # Copied whole from `assets/profiles/event-modelling/commands/`; listed because the documentation names them in order.
 EVENT_COMMANDS = ("example-map", "validate-code-against-model")
 
@@ -330,6 +330,7 @@ def command_files(
         "commands/cruise-settings.md": cruise_settings_command(layout),
         "commands/cruise-status.md": cruise_status_command(layout),
         "commands/cruise-stop.md": cruise_stop_command(layout),
+        "commands/cruise-tell.md": cruise_tell_command(layout),
         "commands/where-are-we.md": where_are_we_command(event, target),
         "commands/whats-next.md": whats_next_command(event),
         "commands/gaps.md": gaps_command(event),

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/src/slipwai/project/cruise.py

@@ -21,6 +21,7 @@ from .cruise_agents import DECISIONS, OWNER_BRIEF, SKIPPER
 from .cruise_hand import hand_section
 from .cruise_record import CHECKPOINT, CHECKPOINT_ENTRY, DECISION_ENTRY, STOP_FILE
 from .cruise_stops import LOG, REPORT, stop_table
+from .cruise_told import boundary_asks, seat_queues, told_argument
 from .cruise_unblock import unblock_section
 
 CONFIG = ".specify/cruise.json"
@@ -96,7 +97,7 @@ def cruise_command(
     )
     return f"""---
 description: Run /drive as driver and product owner, iteration after iteration, until every specification is satisfied — stopping only for a human
-argument-hint: [--feature <name>] [kick-off: what this run is for, where the brief or PRD is] | unblock: <what the outer loop saw>
+argument-hint: [--feature <name>] [kick-off: what this run is for, where the brief or PRD is] | unblock: <what the outer loop saw> | told: <a person's message>
 ---
 
 # Cruise
@@ -142,7 +143,7 @@ states goes into the owner brief (`{OWNER_BRIEF}`), a scope it sets is a decisio
 anything else. Two things the runner passes itself recur: a feature named with `--feature` on `run` or `start`
 (`{layout.make} cruise FEATURE=<name>`) is the first word of every iteration's argument and scopes the run to that
 feature's specification — the ladder is entered for it and no other — and `unblock: <reason>` is what the runner
-says when a run makes no progress (*Blocked: the bosun protocol*, below).
+says when a run makes no progress (*Blocked: the bosun protocol*, below). {told_argument(SCRIPT)}
 
 ## The watch seat
 
@@ -162,7 +163,7 @@ never a reason to run a stage of the ladder in this session.
 **A person typing here is talking to you, not stopping the run.** Answer them — what the feed shows, what
 `{CONFIG}` says (`python3 {SCRIPT}` prints every setting and what it controls), what `python3 {SCRIPT} status`
 says, what `{DECISIONS}` records — and change a setting through `/cruise-settings` where they ask; it takes
-effect at the next iteration. Then watch again. Only `touch {STOP_FILE}`, `python3 {SCRIPT} stop`, or
+effect at the next iteration. {seat_queues(SCRIPT)} Then watch again. Only `touch {STOP_FILE}`, `python3 {SCRIPT} stop`, or
 `{layout.make} cruise-stop` ends the run, and only when they ask for that.
 
 ## Run the ladder, and answer at its stops
@@ -229,7 +230,7 @@ the unit is one slice through Phase 4 and its done marker, or one concurrent fan
 split order. `commands/drive.md` says *do not wait to be invoked again*; here the
 outer loop is what re-invokes, with a fresh context, which is the rule every delegate already lives by.
 Between stages, look for `{STOP_FILE}`: present, finish the stage's own writes, commit what is green, and end
-on `{LAST_LINES[3]}`.
+on `{LAST_LINES[3]}`. {boundary_asks(SCRIPT)}
 At every stage boundary and every delegation, rewrite the checkpoint (*Checkpoint*, below).
 Where nothing can move — every ready slice blocked and the bosun could not move one, or a blocker is on the
 catastrophic list — end with `parked` and the exact thing a person must provide or decide; the loop waits,

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/src/slipwai/project/cruise_record.py

@@ -21,6 +21,10 @@ RUNNER_LOG = ".specify/cruise-run.log"
 RUNNER_STREAM = ".specify/cruise-stream.jsonl"
 WATCH_CURSOR = ".specify/cruise-watch.cursor"
 LAST_RESPONSE = ".specify/cruise-last-response.txt"
+# What a person queued for the run through `tell`, until an iteration takes it; and what an iteration was given,
+# until the runner writes it into that iteration's log entry.
+INBOX = ".specify/cruise-inbox.jsonl"
+TOLD = ".specify/cruise-told.jsonl"
 DECISION_ENTRY = f"""## D<n> — <the question, in one line>
 - **Stage:** <stage> · **Slice:** <id> · **When:** <ISO instant> · **Iteration:** <n>
 - **Question:** <as the stage raised it>

{slipwai-1.2.0.dev44 → slipwai-1.2.0.dev46}/src/slipwai/project/cruise_seat.py

@@ -1,6 +1,6 @@
-"""The two commands a person types beside a running `/cruise`: `/cruise-status` and `/cruise-stop`.
+"""The three commands a person types beside a running `/cruise`: `/cruise-status`, `/cruise-stop` and `/cruise-tell`.
 
-Both are a shell command and the rule for what to do with what it printed. The rule matters more than the
+Each is a shell command and the rule for what to do with what it printed. The rule matters more than the
 command: a harness folds a command's output to a few lines, so a status or a feed reaches a person only through
 the reply, and each of these says so in the same words the watch seat in `commands/cruise.md` uses.
 """
@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from ..layout import AT_ROOT, Layout
 from .cruise import SCRIPT
-from .cruise_record import RUNNER_LOG, STOP_FILE
+from .cruise_record import INBOX, RUNNER_LOG, STOP_FILE
 
 # The rule every seat command shares: the harness folds a command's output, so the reply carries it.
 VERBATIM = ("Put every line it printed in your reply, unchanged, in a fenced block, before anything else: the harness "
@@ -64,3 +64,35 @@ start another run until it is removed — `rm {STOP_FILE}` when they want one. W
 script says so and the file is written anyway, for the same reason. `{layout.make} cruise-stop` is the same
 from a terminal, `CRUISE_FLAGS=--now` for the immediate form.
 """
+
+
+def cruise_tell_command(layout: Layout = AT_ROOT) -> str:
+    """`/cruise-tell`: queue a message for the next iteration, or end the one in flight for it with `--now`."""
+    return f"""---
+description: Queue a message for a running /cruise — a steer, a fact it lacked, a scope — which the next iteration carries; `--now` ends the iteration in flight for it
+argument-hint: [--now] <what the run should know or do next>
+---
+
+# Cruise tell
+
+A person's word to a run that is already going. It is queued, never pushed into the iteration in flight: the
+runner reads the inbox before it starts each iteration and hands the message over as `told: <message>` in that
+iteration's argument — the route the kick-off takes — and the iteration itself asks for what was queued
+between stages. With `--now` as the first word, the iteration in flight is ended for it, the way `/cruise-stop
+now` ends one, and the next iteration starts at once with the message; its increment commits are on the slice
+branch, and the stage's uncommitted work is what it costs.
+
+```sh
+python3 {SCRIPT} tell <<'EOF'
+$ARGUMENTS
+EOF
+```
+
+The message goes in as written — the quoted heredoc is so a quote or a `$` inside it never reaches the shell —
+and `--now` is read from its first word. {VERBATIM} It says whether the message waits for the iteration in
+flight to end, resumes a parked run, or ended the iteration for it — and, where no runner is running, that the
+first iteration of the next run carries it. What was queued and not yet taken is in `{INBOX}`; `/cruise-status`
+lists it, and every message an iteration was given is in that iteration's entry in the run's log. A message
+is not a setting: `/cruise-settings` is still how a rule of the run changes. `{layout.make} cruise-tell
+MSG="…"` is the same from a terminal, `CRUISE_FLAGS=--now` for the immediate form.
+"""

slipwai-1.2.0.dev46/src/slipwai/project/cruise_told.py

@@ -0,0 +1,41 @@
+"""A person's word to a run under way: what `commands/cruise.md` says about `told: <message>`.
+
+A run used to hear from a person twice — in the kick-off, which reaches the first iteration only, and through
+the stop file. Everything in between meant editing the owner brief and hoping the next iteration read it that
+way. `/cruise-tell` queues a message instead, and the runner hands it to the iteration it starts next as
+`told: <message>` in the argument, the kick-off's own route; the iteration asks for later ones between stages;
+and the watch seat queues what a person types for the run rather than doing anything about it itself. These
+are the three paragraphs of the command that say so, kept beside each other because they name one route.
+"""
+from __future__ import annotations
+
+from .cruise_agents import OWNER_BRIEF
+
+
+def told_argument(script: str) -> str:
+    """The kick-off paragraph's third argument: what a message is, where it reaches, and what to do with it."""
+    return f"""A third is a person's: `told: <message>`
+is what somebody queued for the run through `/cruise-tell` (`python3 {script} tell`) since the last iteration
+started, one `told:` per message in the order they were sent, and it reaches the iteration the runner starts next —
+never the one in flight, unless they ended it for the message. Read it before the first stage and act on it
+first: a steer takes precedence over what the artifacts alone would make this iteration do, a fact the run lacked
+is the answer to a block, and a scope or a preference is written down the way the kick-off is — into the owner
+brief (`{OWNER_BRIEF}`) or a decision entry with `Decided by: human` — so it outlives this iteration. A message
+never changes a setting; say so and point at `/cruise-settings` where one asks for that."""
+
+
+def seat_queues(script: str) -> str:
+    """The watch seat's rule for something a person types that is for the run, not for the seat."""
+    return f"""Where what they typed is for the run — a steer, a fact it was missing, a scope, an
+answer to the question it parked on — queue it with `python3 {script} tell <<'EOF'` … `EOF` (`/cruise-tell`),
+the message as they said it, and repeat what the script printed: the next iteration carries it, a parked run
+resumes with it, and `--now` as its first word ends the iteration in flight for it, which is done only when they
+ask for that."""
+
+
+def boundary_asks(script: str) -> str:
+    """The iteration contract's read between stages, beside the look for the stop file."""
+    return f"""At the same boundaries run `python3 {script} told`: it prints what a person queued through
+`/cruise-tell` since this iteration started, one `told:` line each, or nothing — and what it printed is acted on
+before the next stage, exactly as a `told:` argument would have been; it is taken as it is printed, so the next
+iteration is not given it again, and the runner puts it in this iteration's log entry."""