@agfpd/iapeer 0.4.100 → 0.4.102

package/docs/06-storage.md

@@ -95,7 +95,7 @@ A peer's system prompt points here — `~/.iapeer/docs/`, one folder per package
 ```
 
 - **`peer-profile.json`** — the peer's card and the single source of truth about it (the fields are covered in [03 — Peers, runtimes, identity](03-peers-runtimes-identity.md)).
-- **`launch.env`** — a `KEY=VALUE` file for a specific peer+runtime pair: extra launch arguments (`PEER_START_ARGS`) and environment variables. So one peer can be given special launch flags without touching the rest.
+- **`launch.env`** — a `KEY=VALUE` file for a specific peer+runtime pair: extra launch arguments (`PEER_START_ARGS`) and environment variables. So one peer can be given special launch flags without touching the rest. `create`/`init` scaffold it as an all-comment skeleton for every agentic runtime scope (behaves exactly like no file until edited), so fleet-wide launch.env operations never skip a peer for lack of the file; an existing file is never overwritten.
 
 A peer's working folder doesn't have to live under `~/.iapeer/peers/`. By default `iapeer create` puts it there, but any folder can be made a peer with `iapeer init` — then `.iapeer/` appears right inside it.
 

package/docs/19-notices.md

@@ -124,6 +124,46 @@ a stable *transition* clock, and the `updated_at_ms > since` boundary fires exac
 then falls behind forever. A goal blocked while the daemon was down is missed — the same
 honest boundary `peer-mute` already has (§7).
 
+**Only the peer's CURRENT thread counts.** `thread_goals` is keyed by thread_id, so a thread the
+peer has abandoned keeps its last goal row forever. Measured live 16.07.2026: a peer escaped a
+blocked goal the only way its tools allowed — a fresh session — and ended up with two rows,
+`blocked` on the dead thread and `active` on the live one. Reporting the fossil would tell the
+owner an objective is stalled while the peer is working it. So a goal is attributed only on the
+cwd's newest thread (`recency_at_ms`); a fossil is silent.
+
+### Recovery — `iapeer goal <peer> <resume|clear|pause>`
+
+A notice states a fact the peer cannot state. For `peer-goal-stalled` the owner then hits a second
+wall: **the peer cannot fix it either.** Codex splits goal control, and the model's half has no
+exit — `update_goal` may only mark complete|blocked ("pause, resume, budget-limited, and
+usage-limited status changes are controlled by the user or system"), and `create_goal` is refused
+while a goal is unfinished. An agent peer whose goal blocks can only lie (mark an unachieved
+objective `complete`, which its own prompt forbids) or restart its session and lose the thread.
+
+The transition out exists — it is human-only. The TUI's `/goal [<objective>|clear|edit|pause|
+resume]` calls `thread/goal/set`, an unconditional upsert that sets Active from any status, and
+`thread_goal_actions.rs` treats `Paused | Blocked | UsageLimited` as resumable. The daemon is the
+peer's keyboard, so the verb presses it:
+
+| sub | effect |
+|---|---|
+| `resume` | the SAME goal, `blocked` → `active`; codex resumes injecting its own continuation turns |
+| `clear` | the goal is removed ⇒ the peer's OWN `create_goal` stops being refused — the supported route to a *new* objective, authored by the agent rather than by us |
+| `pause` | operator park |
+
+`/goal <objective>` is deliberately NOT offered: replacing an unfinished goal opens a "Replace
+goal?" modal, and blind-typing past a modal is how the wrong option gets picked. Subcommands are a
+closed whitelist — caller text is never interpolated into a keystroke stream. A claude peer returns
+`unsupported` (it has no thread goals; `/goal` would land as literal text in its composer).
+
+**Success is gated on codex's goal store, never on keystrokes being accepted** — a pty write proves
+the bytes left us, not that the TUI acted (§the delivery contour learned this the hard way). The
+verb reads the goal row before and after and reports the transition it can see; a session that took
+the text but never acted returns `unchanged`, not success. iapeer only ever READS codex's sqlite.
+
+Verified live 16.07.2026 on a real codex peer: `blocked → active` in ~1 s, same `goal_id`, same
+thread, no self-fresh, and auto-continuation genuinely resumed.
+
 ## 3. What the owner is told — and what is deliberately withheld
 
 A notice states who, which runtime, which error type, which model, and when the wall lifts.

package/docs/ru/06-/321/205/321/200/320/260/320/275/320/265/320/275/320/270/320/265.md

@@ -95,7 +95,7 @@
 ```
 
 - **`peer-profile.json`** — карточка пира и единственный источник истины о нём (поля разобраны в [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md)).
-- **`launch.env`** — файл вида `KEY=VALUE` для конкретной пары пир+рантайм: дополнительные аргументы запуска (`PEER_START_ARGS`) и переменные окружения. Так одному пиру можно задать особые флаги запуска, не трогая остальных.
+- **`launch.env`** — файл вида `KEY=VALUE` для конкретной пары пир+рантайм: дополнительные аргументы запуска (`PEER_START_ARGS`) и переменные окружения. Так одному пиру можно задать особые флаги запуска, не трогая остальных. `create`/`init` скаффолдят его как скелет из одних комментариев для каждого агентского рантайм-скоупа (до правки ведёт себя ровно как отсутствие файла), поэтому массовые операции над launch.env не пропускают пира из-за отсутствия файла; существующий файл никогда не перезаписывается.
 
 Рабочая папка пира не обязана лежать в `~/.iapeer/peers/`. По умолчанию `iapeer create` кладёт её туда, но пиром можно сделать любую папку командой `iapeer init` — тогда `.iapeer/` появится прямо в ней.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.100",
+  "version": "0.4.102",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -607,6 +607,92 @@ export interface CompactPeerOutcome {
  * crashed / never-run / non-resumable target returns an honest "nothing to compact"
  * instead of starting a fresh empty session and compacting that.
  */
+/** `iapeer goal` outcomes. `action` is what HAPPENED, never what we typed. */
+export interface GoalPeerOutcome {
+  personality: string
+  runtime: string
+  action: 'changed' | 'cleared' | 'no-goal' | 'unchanged' | 'unsupported' | 'offline'
+  from?: string
+  to?: string
+  reason?: string
+}
+
+/** How long we wait for codex to actually apply `/goal <sub>` before calling it unchanged. */
+const GOAL_APPLY_TIMEOUT_MS = 8000
+const GOAL_APPLY_POLL_MS = 250
+
+/**
+ * Drive a codex peer's thread goal out of a state its OWN tools cannot leave (docs/19 §2a).
+ *
+ * WHY THIS VERB EXISTS. Codex's goal control is split: the model may only mark complete|blocked,
+ * and `create_goal` is refused while a goal is unfinished — yet a transient turn error blocks a
+ * goal all by itself. So a headless peer can end up with a dead objective and NO way back except
+ * restarting its session and losing the thread. The transitions out of `blocked` exist, but only
+ * on the human's keyboard (`/goal resume|clear|pause`). We are the peer's keyboard.
+ *
+ * SUCCESS IS GATED ON THE GOAL STORE, not on keystrokes being accepted. Sending bytes into a pty
+ * proves nothing about whether the TUI acted on them — the delivery contour learned that the hard
+ * way. So we read codex's own goal row before and after, and report the transition we can SEE.
+ */
+export async function goalPeer(
+  personality: string,
+  sub: string,
+  runtime: string | undefined,
+  opts: CliEnvOptions & {
+    controlFn?: typeof routeControl
+    /** Injected goal reader (tests). Default: codex's own goal store, read-only. */
+    readGoalFn?: (cwd: string) => Promise<{ status: string; threadId: string } | null>
+    sleepFn?: (ms: number) => Promise<void>
+    timeoutMs?: number
+  } = {},
+): Promise<GoalPeerOutcome> {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) throw new Error(`peer "${personality}" is not registered`)
+  // Omitted runtime resolves the same way every operator verb resolves it (docs: the single
+  // resolvePeerRuntime authority) — never a hardcoded guess.
+  const rt: string = (runtime as Runtime | undefined) ?? resolvePeerRuntime(peer, cfg, env)
+  // Goals are a codex feature. Saying so beats typing '/goal' into a claude composer, where it
+  // would land as literal text in the peer's next message.
+  if (rt !== 'codex') {
+    return { personality, runtime: rt, action: 'unsupported', reason: `thread goals are a codex feature; "${personality}" is on ${rt}` }
+  }
+  const control = opts.controlFn ?? routeControl
+  const sleep = opts.sleepFn ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)))
+  const readGoal =
+    opts.readGoalFn ??
+    (async (cwd: string) => {
+      const { readGoalRows, readCurrentThreadByCwd, resolveGoalWatchPaths } = await import('../daemon/goalwatch.ts')
+      const home = resolveGoalWatchPaths(env).codexHome
+      const current = (await readCurrentThreadByCwd(home, [cwd])).get(cwd)
+      if (!current) return null
+      const row = (await readGoalRows(home)).find(g => g.threadId === current)
+      return row ? { status: row.status, threadId: row.threadId } : null
+    })
+
+  const before = await readGoal(peer.cwd)
+  if (!before) return { personality, runtime: rt, action: 'no-goal', reason: 'this peer has no goal on its current thread' }
+
+  const r = await control(personality, rt, { name: 'goal', args: [sub] })
+  if (!r.ok) return { personality, runtime: rt, action: 'offline', from: before.status, reason: r.error.message }
+
+  const deadline = Date.now() + (opts.timeoutMs ?? GOAL_APPLY_TIMEOUT_MS)
+  while (Date.now() < deadline) {
+    await sleep(GOAL_APPLY_POLL_MS)
+    const now = await readGoal(peer.cwd)
+    if (!now) return { personality, runtime: rt, action: 'cleared', from: before.status }
+    if (now.status !== before.status) return { personality, runtime: rt, action: 'changed', from: before.status, to: now.status }
+  }
+  return {
+    personality,
+    runtime: rt,
+    action: 'unchanged',
+    from: before.status,
+    reason: `goal still "${before.status}" ${GOAL_APPLY_TIMEOUT_MS}ms after /goal ${sub} — the session may be mid-turn (the composer takes the text but does not act on it until the turn ends)`,
+  }
+}
+
 export async function compactPeer(
   personality: string,
   runtime: string | undefined,
@@ -2542,6 +2628,24 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         errOut(`compact: ${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
         return 1
       }
+      case 'goal': {
+        // Recovery for a codex thread goal the peer's OWN tools cannot fix (docs/19 §2a).
+        const sub = positionals[1]
+        if (!positionals[0] || !sub) {
+          return argErr(errOut, 'goal needs a peer and a subcommand — usage: iapeer goal <peer> <resume|clear|pause> [runtime]')
+        }
+        const o = await goalPeer(positionals[0], sub, positionals[2], { env })
+        if (o.action === 'changed') {
+          out(`goal → ${o.personality} (${o.runtime}): ${o.from} → ${o.to}\n`)
+          return 0
+        }
+        if (o.action === 'cleared') {
+          out(`goal → ${o.personality} (${o.runtime}): ${o.from} → cleared (the peer can create_goal again)\n`)
+          return 0
+        }
+        errOut(`goal: ${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        return 1
+      }
       case 'connect': {
         // Per-peer channel attachment in ONE flow (design «Onboard костяка» §(в)):
         // `connect telegram <peer> [--token <t>]`. The human owes only the token;

package/src/daemon/goalwatch.ts

@@ -128,6 +128,10 @@ export function selectStalledGoals(
   cwdByThread: Map<string, string>,
   peerByCwd: (cwd: string) => string | undefined,
   sinceMs: number,
+  /** cwd → the peer's CURRENT thread (see readCurrentThreadByCwd). A goal on any OTHER thread is
+   *  an abandoned session's leftover and is NOT this peer's objective. Omitted → no gate (the
+   *  pure-selection tests that predate the gate). */
+  currentThreadByCwd?: Map<string, string>,
 ): GoalDetection[] {
   const out: GoalDetection[] = []
   for (const g of goals) {
@@ -137,6 +141,12 @@ export function selectStalledGoals(
     if (!cwd) continue // thread not in the state DB → unattributable; ignore rather than guess
     const personality = peerByCwd(cwd)
     if (!personality) continue // a human's own codex thread — never notify
+    if (currentThreadByCwd) {
+      const current = currentThreadByCwd.get(cwd)
+      // A stalled goal on a thread the peer has moved on from is not news — it is a fossil. The
+      // peer may well be working the same objective on its current thread right now.
+      if (!current || current !== g.threadId) continue
+    }
     out.push({
       personality,
       runtime: 'codex',
@@ -270,6 +280,53 @@ export async function readThreadCwds(codexHome: string, threadIds: string[]): Pr
   return out
 }
 
+/**
+ * The CURRENT thread of each cwd — the newest by codex's own recency clock.
+ *
+ * WHY THIS GATES THE NOTICE. A peer's goal rows outlive its threads: `thread_goals` is keyed by
+ * thread_id, so a thread the peer has ABANDONED keeps its last goal row forever. Measured live
+ * 16.07.2026: a peer escaped a blocked goal the only way its tools allowed — a fresh session —
+ * and ended up with TWO rows, `blocked` on the dead thread and `active` on the live one. Reporting
+ * the dead row would tell the owner an objective is stalled while the peer is, in fact, working it
+ * on its current thread. That notice would be one-shot and WRONG, which is worse than noisy: the
+ * whole contract of this surface is that a card means something真 (docs/19 §2a).
+ *
+ * So a goal counts only on the cwd's newest thread. `recency_at_ms` is codex's field for exactly
+ * this; `updated_at_ms` is the fallback when it is absent.
+ */
+export async function readCurrentThreadByCwd(codexHome: string, cwds: string[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  if (cwds.length === 0) return out
+  const path = findVersionedDb(codexHome, 'state')
+  if (!path) return out
+  const db = await openReadOnly(path)
+  if (!db) return out
+  try {
+    const holes = cwds.map(() => '?').join(',')
+    const rows = db
+      .query(
+        `SELECT id, cwd, COALESCE(recency_at_ms, updated_at_ms) AS rank FROM threads
+         WHERE cwd IN (${holes}) ORDER BY rank ASC`,
+      )
+      .all(...cwds) as Array<Record<string, unknown>>
+    // ASC + overwrite ⇒ the LAST write per cwd is the newest thread.
+    for (const r of rows) {
+      const id = str(r.id)
+      const cwd = str(r.cwd)
+      if (id && cwd) out.set(cwd, id)
+    }
+  } catch {
+    /* unrecognised schema → no gate we can trust → caller falls back to not notifying */
+  } finally {
+    try {
+      db.close()
+    } catch {
+      /* best-effort */
+    }
+  }
+  return out
+}
+
 export interface GoalScanDeps extends GoalWatchPaths {
   /** personality ← cwd. Built from the registry by the composition point. */
   peerByCwd: (cwd: string) => string | undefined
@@ -286,7 +343,10 @@ export async function scanStalledGoals(deps: GoalScanDeps, sinceMs: number): Pro
     deps.codexHome,
     candidates.map(g => g.threadId).filter(Boolean),
   )
-  return selectStalledGoals(candidates, cwds, deps.peerByCwd, floor)
+  // Gate on the cwd's CURRENT thread — a fossil goal on an abandoned session is not this peer's
+  // objective (see readCurrentThreadByCwd).
+  const current = await readCurrentThreadByCwd(deps.codexHome, [...new Set(cwds.values())])
+  return selectStalledGoals(candidates, cwds, deps.peerByCwd, floor, current)
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/launch/adapters/codex.ts

@@ -46,6 +46,19 @@ import { codexSessionCwd, lastTimestampedEntryMs } from './transcriptTail.ts'
 import { detectNumberedModal } from './modalDetect.ts'
 import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 
+/**
+ * The `/goal` subcommands we will type into a live codex session (see executeControl → 'goal').
+ *
+ * DIALOG-FREE ONLY. Codex's own usage line is `/goal [<objective>|clear|edit|pause|resume]`, but:
+ *   - `<objective>` on an unfinished goal opens a "Replace goal?" modal (tui/thread_goal_actions.rs
+ *     `should_confirm_before_replacing_goal` → true for every status except Complete);
+ *   - `edit` opens $EDITOR.
+ * Both need us to blind-type past an interactive prompt, which is how a wrong option gets picked.
+ * `resume` / `clear` / `pause` apply straight through. `resume` is the one that matters: it is the
+ * documented user-side transition out of `blocked`, the state the model's own tools cannot leave.
+ */
+const GOAL_SUBCOMMANDS = new Set(['resume', 'clear', 'pause'])
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Boot dialog markers (watcher.codexUpdate/DirTrust/HooksReview, 253-261)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -399,11 +412,39 @@ export const codexAdapter: RuntimeAdapter = {
    *     conversation to prevent hitting the context limit») and a live run
    *     yields «• Context compacted». The 0.136-era "codex has no /compact"
    *     finding is stale; the mapping is keyboard-identical to claude's.
+   *   - goal <sub> → type '/goal <sub>' then Enter. The recovery path for a thread goal a
+   *     headless peer CANNOT fix with its own tools (docs/19 §2a). Codex exposes goal control
+   *     asymmetrically: the MODEL's `update_goal` may only mark complete|blocked ("pause,
+   *     resume, budget-limited, and usage-limited status changes are controlled by the user or
+   *     system"), and `create_goal` refuses while a goal is unfinished ("complete the existing
+   *     goal first"). So once a goal is `blocked` — which a transient turn error does BY ITSELF,
+   *     without the model — an agent peer has no way back and must restart its session. The
+   *     capability is not missing, it is HUMAN-ONLY: the TUI's `/goal [<objective>|clear|edit|
+   *     pause|resume]` calls thread/goal/set, an unconditional upsert that sets Active from any
+   *     status. We are the peer's keyboard, so we press it for them.
+   *
+   *     Verified live 16.07.2026 on a real codex peer: a blocked goal went blocked → ACTIVE and
+   *     codex resumed injecting its own continuation turns — same thread, same goal_id, no
+   *     self-fresh, nothing written to codex's sqlite by us.
+   *
+   *     Only DIALOG-FREE subcommands are allowed (see GOAL_SUBCOMMANDS). `/goal <objective>` is
+   *     deliberately NOT offered: replacing an unfinished goal opens a "Replace goal?"
+   *     confirmation, and blind-typing past a modal is how you submit the wrong answer. The
+   *     supported way to a NEW objective is `clear` (no goal → the peer's own `create_goal`
+   *     stops being refused), which keeps the objective the AGENT's to author, not ours.
    *   - anything else → null.
    */
   executeControl(command: ControlCommand): ControlPlan | null {
     if (command.name === 'interrupt') return { sequence: [['Escape']] }
     if (command.name === 'compact') return { sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 }
+    if (command.name === 'goal') {
+      const sub = command.args?.[0]
+      // Closed set — never interpolate caller text into a keystroke stream. An objective is
+      // free-form and would need the modal above; a typo'd subcommand must fail here, not land
+      // as literal garbage in a live composer.
+      if (!sub || !GOAL_SUBCOMMANDS.has(sub)) return null
+      return { sequence: [['-l', `/goal ${sub}`], ['Enter']], stepDelayMs: 300 }
+    }
     return null
   },
 }

package/src/launch/ptyHost.ts

@@ -183,15 +183,25 @@ export function deliverHosted(identity: string, message: string, env: NodeJS.Pro
  * (transport/index.ts). NOT a delivery: it pastes nothing and carries no payload, it only presses
  * Enter on whatever the composer already holds.
  *
- * WHY THIS EXISTS. deliverToHost is paste → 300 ms settle → CR. When the paste carries attachments
- * the receiving TUI hoists them (reads + encodes the files, rewrites the composer), and the CR fired
- * on the fixed settle lands MID-HOIST and is swallowed — the composer keeps the envelope and NO turn
- * is ever submitted. Proven live 16.07.2026 on an idle claude receiver: att=4 (2.7 MB) sat unsubmitted
- * with a frozen transcript for 3m33s and moved only when an unrelated later delivery's CR arrived; the
- * SAME envelope with an 8 s settle submitted itself in 4 s (single-factor isolation).
+ * WHY THIS EXISTS. deliverToHost is paste → fixed 300 ms settle → CR. Sometimes that CR is EATEN: the
+ * composer keeps the envelope and NO turn is ever submitted, so the message is never processed and the
+ * landed-confirm has nothing to find. Measured live 16.07.2026 (claude receivers):
  *
- * Sent through the CONTROL channel (bare bytes, no bracketed paste) precisely because it must be a
- * keystroke, not a pasted literal.
+ *   • FIRST attachment-bearing delivery into a session → CR eaten. Two independent sessions hung this
+ *     way; one sat with a byte-frozen transcript for 180 s with NOTHING else sent, and moved only when
+ *     an unrelated later delivery's CR arrived. The payload was never lost — it sat in the composer,
+ *     still carrying its own original ts.
+ *   • EVERY LATER attachment delivery into that same session → the first CR works (~0.7–1 s, even for
+ *     9.3 MB of fresh incompressible PNGs).
+ *
+ * WHY the first one is different is NOT known, and this code deliberately does not guess. An earlier
+ * reading — "hoisting is slow, so the CR lands mid-hoist" — was RETRACTED: it rested on a settle=8000
+ * run that looked decisive but was confounded (that session had already taken its first attachment, so
+ * any settle would have worked). Do not re-derive a hoist-duration constant from it.
+ *
+ * That unknown is exactly why the retry is cause-agnostic: it does not model WHY a CR was eaten, it
+ * just presses Enter again while nothing has landed. Sent through the CONTROL channel (bare bytes, no
+ * bracketed paste) because it must arrive as a keystroke, not a pasted literal.
  */
 export function resubmitHosted(identity: string, env: NodeJS.ProcessEnv = process.env): Promise<DeliverResult> {
   return sendControlToHost(hostRunDir(env), identity, [Buffer.from('\r', 'utf8')])

package/src/storage/index.ts

@@ -197,6 +197,10 @@ export function ensureLocalRuntimeScopes(cwd: string, runtimes: readonly Runtime
   mkdirSync(root, { recursive: true, mode: DIR_MODE })
   for (const runtime of supportedLocalRuntimeScopes(runtimes)) {
     mkdirSync(join(root, runtime, PLUGINS_DIR, IAP_PLUGIN_DIR), { recursive: true, mode: DIR_MODE })
+    // Default launch.env skeleton — every agentic runtime scope carries the knob
+    // from birth, so fleet-wide launch.env operations (e.g. mass PEER_START_ARGS
+    // edits) never skip a peer for lack of the file. Existing files are untouched.
+    ensureLaunchEnv(cwd, runtime)
   }
 }
 
@@ -207,11 +211,45 @@ export function ensureLocalRuntimeScopes(cwd: string, runtimes: readonly Runtime
 export const LAUNCH_ENV_FILE = 'launch.env'
 
 /** `<cwd>/.iapeer/runtimes/<runtime>/launch.env` — the per-peer per-runtime launch
- *  fragment (PEER_START_ARGS + extra peer env). Written by init, read at launch. */
+ *  fragment (PEER_START_ARGS + extra peer env). Scaffolded as an all-comment
+ *  skeleton by create/init (ensureLocalRuntimeScopes) for every agentic runtime
+ *  scope; the operator uncomments/edits it. Read at launch; missing → empty. */
 export function peerLaunchEnvPath(cwd: string, runtime: Runtime): string {
   return join(cwd, IAPEER_DIR, RUNTIMES_DIR, runtime, LAUNCH_ENV_FILE)
 }
 
+/** The default launch.env skeleton. ALL lines are comments — deliberately: it must
+ *  parse to exactly the missing-file semantics ({startArgs: [], env: {}}, and
+ *  crucially NO PEER_DISALLOWED_TOOLS key, whose present-empty ≠ absent is the
+ *  opt-in gate). No trailing comments on the example lines — the parser keeps
+ *  everything after `=` as the value, so `KEY=x # note` would poison the value. */
+export const LAUNCH_ENV_TEMPLATE = `# launch.env — optional per-peer per-runtime launch overrides (iapeer, docs/06-storage).
+# Format: one KEY=VALUE per line (bash-style; an \`export \` prefix is allowed).
+# Blank lines and lines starting with # are ignored. Do NOT put a trailing
+# comment after a value — everything after \`=\` is taken verbatim as the value.
+# This skeleton is all comments: it behaves exactly like no file at all.
+#
+# Extra CLI args appended after the runtime's base argv (whitespace-split):
+#PEER_START_ARGS=""
+#
+# claude only — --disallowedTools override. Key absent = adapter default for the
+# whole fleet; present-empty ("") = omit the flag; a value = pass it verbatim:
+#PEER_DISALLOWED_TOOLS=""
+#
+# Any other KEY=VALUE becomes an env var of the peer's session:
+#MY_VAR=value
+`
+
+/** Create the default launch.env skeleton if (and only if) the file does not
+ *  exist yet — an existing operator-edited file is NEVER touched. 0600 like the
+ *  rest of the tree (an operator may later put secrets in it). */
+export function ensureLaunchEnv(cwd: string, runtime: Runtime): void {
+  const path = peerLaunchEnvPath(cwd, runtime)
+  if (existsSync(path)) return
+  mkdirSync(dirname(path), { recursive: true, mode: DIR_MODE })
+  writeFileAtomic(path, LAUNCH_ENV_TEMPLATE)
+}
+
 export interface LaunchEnv {
   /** Tokens from PEER_START_ARGS, appended AFTER the adapter's base argv flags. */
   startArgs: string[]
@@ -232,9 +270,10 @@ export interface LaunchEnv {
  * reproduced here with a whitespace split (faithful to that semantics; a value
  * with embedded spaces was never one arg in the bash either). Surrounding single/
  * double quotes around a value are stripped. Lines that are blank or start with
- * `#` are ignored. A missing/unreadable file → empty (no flags, no env). This is a
- * deliberately MINIMAL parser (assignments only — no command substitution, no
- * conditionals); init writes the file, so the format is controlled.
+ * `#` are ignored. A missing/unreadable file → empty (no flags, no env); the
+ * scaffolded all-comment skeleton (LAUNCH_ENV_TEMPLATE) parses to the same. This
+ * is a deliberately MINIMAL parser (assignments only — no command substitution, no
+ * conditionals); the format is a controlled convention, not arbitrary shell.
  */
 export function readLaunchEnv(cwd: string, runtime: Runtime): LaunchEnv {
   let text: string

package/src/transport/index.ts

@@ -185,24 +185,28 @@ const LIVENESS_POLL_MS = 100
 const CONFIRM_GRACE_MS = 4000
 
 // ATTACHMENT grace. The "sub-second" assumption above holds only WITHOUT attachments: an att>0 paste
-// makes the receiving TUI hoist the files (read + encode, rewrite the composer) before any turn can
-// begin, which takes seconds.
+// makes the receiving TUI ingest the files (hoist them into image blocks, rewrite the composer) before
+// any turn can begin, so acceptance is not sub-second.
 //
 // CORRECTED 16.07.2026 — the model this number was first built on was WRONG. The original note here
 // read the 15.07 att=4 measurement as "the receiver writes the user-record when it BEGINS the turn,
 // and loading the images pushed that start ~22 s out", i.e. a LATE SELF-START that a longer grace
-// would catch. A confound-free repro disproved it: att=4 (2.7 MB) into a claude receiver idle 2m17s,
-// with NOTHING else sent, left the transcript byte-frozen for 180 s — the turn NEVER started. The
-// 15.07 "22 s self-start" was almost certainly the same confound (an unrelated later delivery poked
-// the session). The real mechanism is a SWALLOWED SUBMIT, not a slow write: deliverToHost is
-// paste → 300 ms settle → CR, and with attachments the CR lands mid-hoist and is eaten. Proven by
-// single-factor isolation: the SAME envelope with an 8 s settle submitted itself in 4 s.
+// would catch. A confound-free repro disproved it: att=4 into a claude receiver idle 2m17s, with
+// NOTHING else sent, left the transcript byte-frozen for 180 s — the turn NEVER started, and the
+// message moved only when an unrelated later delivery poked the session. The 15.07 "22 s self-start"
+// was almost certainly that same confound. There is no late self-start to wait for: the SUBMIT was
+// eaten, so a passive grace of ANY size waits for a record that cannot exist.
 //
-// So a passive grace of ANY size is useless here — it waits for a record that cannot exist, because
-// nothing was ever submitted. What makes the grace meaningful is the SUBMIT-RETRY below: we keep
-// pressing Enter while no record has landed, so the CR that falls after the hoist finishes does the
-// work. 60 s is then an upper BOUND on hoisting a large payload (not a calibrated latency), and it
-// costs nothing on the happy path — the confirm returns the moment the record lands.
+// WHICH deliveries get their CR eaten, measured: the FIRST attachment-bearing delivery into a session
+// (reproduced on two independent sessions, and again on a purpose-built fresh one). Every LATER
+// attachment delivery into the same session submits on the first CR in ~0.7–1 s, even at 9.3 MB. WHY
+// the first differs is UNKNOWN — an intermediate "the CR lands mid-hoist" story was retracted as
+// confounded, so no hoist-duration constant may be derived from it.
+//
+// What makes the grace meaningful is the SUBMIT-RETRY below, which needs no such answer: while no
+// record has landed we keep pressing Enter, and whichever press finds the composer submittable does
+// the work. 60 s is then just a generous give-up BOUND (not a calibrated latency), and it costs
+// nothing on the happy path — the confirm returns the moment the record lands.
 const CONFIRM_GRACE_ATTACHMENTS_MS = 60_000
 
 // Submit-retry cadence — how often, WHILE NO RECORD HAS LANDED, the grace re-presses Enter on the
@@ -213,8 +217,11 @@ const CONFIRM_GRACE_ATTACHMENTS_MS = 60_000
 // the turn already submitted — an empty composer ignores a CR. The loop is gated on `confirm()`
 // being false, so we stop the instant the record appears.
 //
-// Deliberately NOT every poll (100 ms): a CR is a keystroke into a live human-visible session, so it
-// is paced. 1.5 s is far below any plausible hoist time yet spaces the presses.
+// Deliberately NOT every poll (100 ms): a CR is a keystroke into a live, human-visible session, so the
+// presses are spaced rather than machine-gunned. This is a PACING number only — it is explicitly NOT a
+// "how long until the composer is submittable" estimate, because that duration is unknown and the whole
+// point of retrying is not needing it. Raising or lowering it changes only how promptly a stuck message
+// is rescued (measured live: a rescue landed at ~2.3 s with this value), never whether it is.
 const RESUBMIT_INTERVAL_MS = 1500
 
 function envNonNegative(raw: string | undefined): number | null {
@@ -385,10 +392,11 @@ async function deliverViaHost(
   const graceMs = confirmGraceMs(envelopeHasAttachments(envelope))
   const graceDeadline = monotonicMs() + graceMs
   // SUBMIT-RETRY (see RESUBMIT_INTERVAL_MS). deliverToHost already pressed Enter once, on a fixed
-  // settle; if the paste was still hoisting, that CR was eaten and NOTHING is running. So the grace
-  // does not merely WAIT for a record — while none has landed it keeps pressing Enter, and whichever
-  // press falls after the hoist submits the composer. Self-correcting for any payload weight: there is
-  // deliberately NO tuned "how long does hoisting take" constant anywhere in this path.
+  // settle; that CR is sometimes EATEN, and then NOTHING is running and no record can ever appear. So
+  // the grace does not merely WAIT for a record — while none has landed it keeps pressing Enter, and
+  // whichever press finds the composer submittable does the work. Cause-agnostic ON PURPOSE: it does
+  // not model WHY a CR was eaten (still unknown), so there is deliberately no tuned duration constant
+  // on this path — which is also what keeps it correct at any payload weight.
   let nextResubmitAt = monotonicMs() + RESUBMIT_INTERVAL_MS
   while (true) {
     if (confirm(envelope)) return ok(undefined)