fix(agents): unattended turn brief matches how waiting actually works (v0.447.1)

CHANGELOG.md

@@ -8,6 +8,18 @@ new version heading in the same commit.
 
 ## [Unreleased]
 
+## [0.447.1] - 2026-09-17
+### Fixed
+- **The unattended-run brief no longer tells agents three things that stopped being true.** It said
+  `task_wait` "survives your turn ending" (it blocks inside the turn, ~15 min per call on this lane, and a
+  completion never resumes a caller that has exited), that `ask_human` "keeps your session alive while the
+  card is pending" (on this lane it waits ~2 minutes and ending the run cancels the question — the
+  durable path is `task_update` `blocked` with `blockedOn: "human"`, which carries the ask since v0.444.2),
+  and it pointed at `BashOutput`, now a legacy alias of `TaskOutput`. It also forbade polling loops
+  outright, contradicting the both-lanes waiting brief that prescribes short bounded polls; it now forbids
+  only a loop left running across the turn boundary. Adds that the background-work grace ends at `report`,
+  and that a task filed without `autoDispatch` is a proposal, not a way to continue your own work.
+
 ## [0.447.0] - 2026-09-17
 ### Added
 - **Focus check — a nudge when a session goes down a rabbit hole.** The progress verdicts could only see a

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-os",
-  "version": "0.447.0",
+  "version": "0.447.1",
   "description": "A generic, governed operating system for running autonomous agents safely across brands. Ships with a local web console.",
   "license": "MIT",
   "type": "commonjs",

src/edge/background-work.ts

@@ -216,21 +216,30 @@ export const UNATTENDED_TURN_BRIEF =
   'You are running **unattended** — nobody is at this terminal. There is no next prompt: when you stop ' +
   'and hand the turn back, this run is over and the session is torn down. Ending your turn is how you ' +
   'finish, not how you pause.\n\n' +
-  '**So you cannot yield and wait.** Do not end your turn expecting to be woken — not to wait for a ' +
-  'background command, not for a subagent you launched, not for a review, a build, a deploy, or a ' +
-  'person. Do not idle with `sleep`, a polling loop, or a `until [ -f … ]` sentinel: those hold the ' +
-  'turn open at best and are killed with the run at worst. If you launch background work you intend to ' +
-  'use, **stay in the turn and read its result** (`BashOutput` on a background command, or wait for the ' +
-  'subagent you started) before you stop.\n\n' +
-  '**When you genuinely have to wait, use the OS instead of the turn:**\n' +
-  '- `task_wait` (or `task_create({ wait: true })`) — blocks until a delegated agent finishes and ' +
-  'resumes you with its result. This is the supported hand-off; it survives your turn ending.\n' +
-  '- `ask_human` — blocks on a person and keeps your session alive while their Inbox card is pending.\n' +
-  '- `schedule` — defers a FUTURE run of yourself (minutes to days out) when the thing you need cannot ' +
-  'happen inside this run at all. Report what you did first; the scheduled run picks it up.\n' +
-  '- `task_create` — park the remainder as durable work rather than holding a session open for it.\n\n' +
+  '**So you cannot yield and wait.** Do not end your turn expecting to be woken — not by a background ' +
+  'command, a subagent, a delegated task, a review, a build, or a person. A result that arrives after ' +
+  'your run has ended is filed on the task or in the Inbox; it does not bring you back. Waiting INSIDE ' +
+  'the turn is fine (short bounded polls, per the waiting note below); a `sleep` or `until [ -f … ]` ' +
+  'loop left running while you hand the turn back is not. If you launch background work you intend to ' +
+  'use, **stay in the turn and read its result** (`TaskOutput` for a background command or subagent) ' +
+  'before you stop. The OS gives an unfinished background child a short grace period, but only until ' +
+  'you `report` — so read the result first, then report.\n\n' +
+  '**When the thing you need is not coming inside this run, use the OS instead of the turn:**\n' +
+  '- `task_wait` (or `task_create({ wait: true })`) — blocks INSIDE your turn until a delegated agent ' +
+  'finishes, for up to ~15 minutes per call. If it returns "still running", call it again; if you have ' +
+  'to stop first, `report` that the hand-off is in flight.\n' +
+  '- `ask_human` — on this lane it waits only about two minutes, because nobody is watching. If no answer ' +
+  'comes, do not guess on anything risky: if you are working a task, `task_update` it `blocked` with ' +
+  '`blockedOn: "human"` so the question travels with the task and the answer re-opens it, then `report` ' +
+  'and stop. Ending the run cancels the Inbox question itself.\n' +
+  '- `schedule` — defers a FUTURE run of yourself (minutes to days out) for something that cannot ' +
+  'happen inside this run at all: a deploy settling, a reply you expect tomorrow. Report what you did ' +
+  'first; the scheduled run picks it up.\n' +
+  '- `task_create` — hand the remainder to the agent who should do it (`autoDispatch: true`). A task you ' +
+  'file WITHOUT dispatching it is only a proposal a human must accept, so use that for work a person ' +
+  'should decide on, not as a way to continue your own.\n\n' +
   '**Always `report` before you stop.** It is the only record of what happened: an unattended run that ' +
   'ends without one shows up as "no report", the caller waiting on you is left stranded, and everything ' +
   'you did is invisible to the humans and agents downstream. If you are stopping early — blocked, out ' +
   'of budget, out of scope — that is still a `report`, with the outcome and what is left. ' +
-  'Say what remains, and file or schedule it, so the next run starts where you left off.';
+  'Say what remains, and where you parked it, so the next run starts where you left off.';