@agfpd/iapeer 0.4.101 → 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.101",
+  "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/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