@agfpd/iapeer 0.2.77 → 0.2.79

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Artur Agafapudov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -22,8 +22,8 @@ iapeer держит AI-агентов как **живые интерактивн
 
 ## Документация
 
-Документация проекта — в [`docs/`](docs/README.md): продуктовая часть (что это и как пользоваться) и механика изнутри ([`docs/internals/`](docs/internals/README.md)). Этот репозиторий — кодовая реализация.
+Документация проекта — в [`docs/`](https://github.com/agfpd/iapeer/tree/main/docs): продуктовая часть (что это и как пользоваться) и механика изнутри ([`docs/internals/`](https://github.com/agfpd/iapeer/tree/main/docs/internals)). Этот репозиторий — кодовая реализация.
 
 ## Статус
 
-Версия — **0.2.73**. Платформа — macOS/launchd.
+Платформа — macOS/launchd. Актуальная версия — в `package.json` / `iapeer version`.

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.77",
+  "version": "0.2.79",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
+  "license": "Apache-2.0",
+  "author": "agfpd",
+  "homepage": "https://github.com/agfpd/iapeer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agfpd/iapeer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agfpd/iapeer/issues"
+  },
+  "keywords": [
+    "multi-agent",
+    "agents",
+    "mcp",
+    "ipc",
+    "launchd",
+    "bun"
+  ],
   "type": "module",
   "bin": {
     "iapeer": "bin/iapeer"
@@ -9,7 +27,8 @@
   "files": [
     "src",
     "bin",
-    "tsconfig.json"
+    "tsconfig.json",
+    "!src/**/*.test.ts"
   ],
   "exports": {
     ".": "./src/index.ts",

package/src/cli/index.ts

@@ -102,7 +102,7 @@ export interface PeerListing {
   /** The peer's working directory (registry fact). Machine-readable so host-local
    *  tooling (e.g. the memory provider's init/verify rendering doctrine into
    *  <cwd>/.iapeer/) keys on the REGISTRY instead of copying the layout default —
-   *  a layout change must not silently strand consumers (iapeer-memory ask, 10.06). */
+   *  a layout change must not silently strand consumers. */
   cwd: string
   runtimes: RuntimeStatus[]
 }
@@ -235,8 +235,8 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       killSession(sock, identity)
       out.push({ personality, runtime: rt, action: 'bootout', reason: r.status === 0 ? undefined : `launchctl bootout exited ${r.status}${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''}` })
     } else {
-      // A deliberate stop is a CLEAN PARK, not a death (boris 10.06 — stop→start
-      // must survive ≥ idle-reap): park-mark BEFORE the kill so the post-`start`
+      // A deliberate stop is a CLEAN PARK, not a death (stop→start must survive ≥
+      // idle-reap): park-mark BEFORE the kill so the post-`start`
       // wake RESUMES, and drop the supervise session-state with the session so
       // the tick never tags this kill as a death (crash-loop ring stays clean,
       // no reaped-gone death class for a state the daemon knows 100%).
@@ -268,8 +268,8 @@ export function startPeer(personality: string, runtime: string | undefined, opts
     const identity = buildProcessAddress(rt, personality)
     if (isInfraRuntime(rt)) {
       const plist = launchdPlistPath(personality, env)
-      // UNDEAD-JOB-SAFE start (boris's connect-acceptance find 10.06): a bootstrap
-      // right after a bootout used to hit the still-dismantling job (exit 5 I/O
+      // UNDEAD-JOB-SAFE start: a bootstrap right after a bootout used to hit the
+      // still-dismantling job (exit 5 I/O
       // error) and leave the router DOWN. launchctlBootstrap now waits for the
       // job to vanish and retries with backoff (~22 s budget); a failure after
       // every attempt is LOUD with the manual rescue recipe. (Also gains the
@@ -300,8 +300,8 @@ export interface AddRuntimeOutcome {
 
 /**
  * add-runtime <runtime> (--peer <p> | --all) — give EXISTING peers an additional
- * AGENTIC runtime in one command (codex-parity audit, директива Артура 12.06: the
- * fleet-switch enabler — 14/23 peers were claude-only with nothing to switch to).
+ * AGENTIC runtime in one command (the fleet-switch enabler — a claude-only peer
+ * has nothing to switch to).
  * Per target: initPeer({cwd, runtime}) — ensurePeerProfile MERGES runtimes (the
  * default_runtime lever is deliberately untouched — capability ≠ routing flip; see
  * `default-runtime`), scaffolds the runtime scope, and the codex side runs its
@@ -325,8 +325,8 @@ export async function addRuntime(
   if (targets.length === 0) throw new Error(opts.peer ? `peer "${opts.peer}" is not registered` : 'no targets — pass --peer <p> or --all')
   // CROSS-PEER operation: strip the CALLER's identity env (PEER_*) — an operator
   // (or an agent peer) running this from inside their own session would otherwise
-  // poison the TARGET's ensurePeerProfile identity check (live-caught on the very
-  // first 0.2.45 probe: PEER_PERSONALITY="iapeer" vs target "twpar" → failed).
+  // poison the TARGET's ensurePeerProfile identity check (the caller's
+  // PEER_PERSONALITY would mismatch the target personality → failed).
   const cleanEnv: NodeJS.ProcessEnv = { ...env }
   delete cleanEnv.PEER_PERSONALITY
   delete cleanEnv.PEER_RUNTIME
@@ -353,8 +353,8 @@ export async function addRuntime(
   // Self-heal the registry from the locals: provisionPeer's upsert sets the record's
   // default to the PROVISIONED runtime («args.runtime wins» — right for births, wrong
   // here: add-runtime is capability-only and must NOT flip routing). The reindex
-  // REPLACE projection restores the local profile's untouched default (live-caught
-  // on the 0.2.45 probe: registry default flipped to codex while the local kept claude).
+  // REPLACE projection restores the local profile's untouched default (otherwise
+  // the registry default flips to the added runtime while the local keeps its own).
   if (out.some(o => o.action === 'added')) await reindexFromLocals({ env })
   return out
 }
@@ -367,8 +367,8 @@ export interface DefaultRuntimeOutcome {
 
 /**
  * default-runtime <runtime> (--peer <p> | --all) — flip the PRIMARY lever
- * (contract Идентичность: primary держит default_runtime, НЕ порядок runtimes[];
- * linus precedent 11.06). This is the routing/wake/first-launch default — the
+ * (contract Идентичность: primary держит default_runtime, НЕ порядок runtimes[]).
+ * This is the routing/wake/first-launch default — the
  * actual fleet-switch moment is a mass flip of exactly this field. The local
  * profile is rewritten through the H1 merge-writer (default_runtime + the legacy
  * in-sync mirror; normalizeRuntimes re-prepends the new default), then the
@@ -432,7 +432,7 @@ export interface NewPeerOutcome {
 
 /**
  * new <peer> [runtime] — the UNCONDITIONAL fresh-restart control command
- * (docs/Control-команды §new; постановка boris 01:32 12.06, санкция Артура).
+ * (docs/Control-команды §new).
  *
  * The emergency lever for a HUNG or dead agent session: /alias-new covers only
  * the COOPERATIVE path (a live peer reads the expanded prompt and runs
@@ -444,7 +444,7 @@ export interface NewPeerOutcome {
  *   wakeOrSpawn(resume:false, task:'') — fresh BY CONSTRUCTION, the same recipe
  *   as the eager relaunch (the C2 initial_prompt seeds the first turn).
  *
- * exit-0 contract (сверка telegram-runtime): success ⟺ the fresh session is UP
+ * exit-0 contract: success ⟺ the fresh session is UP
  * and READY (verified by the wake's ready gate, not merely scheduled) — for a
  * sleeping, dead AND hung target alike. Duration is a real TUI boot: typically
  * 5–30 s, bounded by cfg.bootDeadlineSecs. Idempotent in effect: each repeat
@@ -645,7 +645,7 @@ export interface RemoveOutcome {
   reason?: string
   /** The removed peer's cwd (registry fact, captured BEFORE the removal). remove
    *  deliberately keeps the folder — user data is never deleted by a registry reap
-   *  (boris's finding 10.06: say so in the output instead of leaving silent orphans). */
+   *  (say so in the output instead of leaving silent orphans). */
   cwd?: string
   /** v1.2: per-runtime unprovision outcomes (`<rt>:<state>`), present when the
    *  slot declares an unprovision command (occasion=remove ran before the purge). */
@@ -660,8 +660,8 @@ export interface RemoveOutcome {
   codexHooksTrust?: string
   /** Identity-keyed lifecycle artifacts purged with the record (state/lifecycle/
    *  `<identity>.*` per runtime). Without this purge a NEWBORN peer reusing the
-   *  personality inherits the dead namesake's parking (live defect, boris 10.06:
-   *  stale .stopped → `mode=refused cause=stopped` on a freshly-created peer). */
+   *  personality inherits the dead namesake's parking (defect: stale .stopped →
+   *  `mode=refused cause=stopped` on a freshly-created peer). */
   purgedState?: string[]
 }
 
@@ -734,7 +734,7 @@ export async function removePeerCli(
     unprovisionOutcomes.push(`failed: ${e instanceof Error ? e.message : String(e)}`)
   }
   // Codex pre-trust cleanup (reap-side counterpart of the birth-time
-  // preTrustCodexCwd; backlog made live by D4 11.06): a removed codex peer must
+  // preTrustCodexCwd): a removed codex peer must
   // not leave its cwd trusted in the host ~/.codex/config.toml forever. After
   // unprovision (the provider sees the peer's last consistent state first),
   // best-effort like everything else on this path.
@@ -800,7 +800,7 @@ export async function sendMessage(
 ): Promise<{ ok: true; delivered_to: { personality: string; runtime: string }; queued?: boolean; queueDepth?: number }> {
   const env = opts.env ?? process.env
   const caller = resolveCallerIdentity(parseIdentity(opts.from), readPeersIndex({ env }))
-  // wake_policy:ephemeral M3 parity (iapeer-memory ask, 10.06): the CLI path used
+  // wake_policy:ephemeral M3 parity: the CLI path used
   // to route an ephemeral target through the normal live/miss path — a notifier
   // burst landed as TURNS in one live worker session instead of serializing
   // through the disk FIFO the daemon path uses. Same seam, ONE difference: the
@@ -822,12 +822,12 @@ export async function sendMessage(
     },
     // noteLiveTopic — CLI-path parity (same seam the daemon wires): a live delivery
     // through the CLI fallback must update the target's .topic marker too, or a
-    // daemon-restart-window send re-opens the stale-marker false-fresh (defect 11.06).
+    // daemon-restart-window send re-opens the stale-marker false-fresh.
     { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}), noteLiveTopic: makeNoteLiveTopic(cfg, env) },
   )
-  // delivery.log sink — CLI-path parity (boris's observability gap 10.06: enqueues
-  // routed through the CLI left to=<peer> at ZERO for the day while real wakes
-  // happened; the daemon tool-path logs, this path was blind). Same fields, plus
+  // delivery.log sink — CLI-path parity (observability gap: enqueues routed
+  // through the CLI left to=<peer> at ZERO while real wakes happened; the daemon
+  // tool-path logs, this path was blind). Same fields, plus
   // path=cli so the two entry points are distinguishable. Both branches logged.
   const { appendDeliveryEvent } = await import('../daemon/deliverylog.ts')
   appendDeliveryEvent(cfg.eventLogDir, {
@@ -849,10 +849,10 @@ export async function sendMessage(
     err: result.ok ? undefined : result.error.message,
   })
   if (!result.ok) throw new Error(result.error.message)
-  // M2 arm-on-outbound — CLI-path parity (live gap 10.06: an ephemeral worker's
-  // final reply sent through the CLI fallback — e.g. inside a daemon-restart
-  // window, four deploys that day — never armed, so the worker idled to the
-  // unarmed bound and stalled its FIFO). Same hook the daemon path uses; ONLY on
+  // M2 arm-on-outbound — CLI-path parity (gap: an ephemeral worker's final reply
+  // sent through the CLI fallback — e.g. inside a daemon-restart window — never
+  // armed, so the worker idled to the unarmed bound and stalled its FIFO). Same
+  // hook the daemon path uses; ONLY on
   // an ok outcome, errors swallowed (arming is best-effort, never fails the send).
   try {
     makeArmEphemeralOnDelivered(cfg)(caller)
@@ -925,7 +925,7 @@ const USAGE = `usage: iapeer <verb> [args]
                                                                  it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer
   remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
   send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
-  <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
+  <runtime>                                                      launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached
   connect telegram <peer> [--token <t>]                          attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)
   enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
   new <peer> [runtime]                                           UNCONDITIONAL fresh restart: canary-clean kill + fresh wake (emergency lever for a hung/dead session — bypasses the peer; exit 0 = fresh session up+ready)
@@ -976,7 +976,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(r.noop ? 'onboard: no marketplace changes (already configured / dry-run)\n' : 'onboard: marketplace(s) registered\n')
         let infraFailed = false
         const infra = typeof flags.infra === 'string' ? flags.infra.split(',').map(s => s.trim()).filter(Boolean) : []
-        // Backbone default-yes steps (design «Onboard костяка», FINAL 10.06). ORDER is
+        // Backbone default-yes steps (design «Onboard костяка»). ORDER is
         // significant: notifier → TELEGRAM (creates the human peer) → memory below
         // (its --human resolves from the natural peer that just appeared). Each step
         // is soft-skip on unavailability; only a REAL deploy/create break fails.
@@ -1025,7 +1025,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         } else if (infra.length) {
           out(`onboard --dry-run: would onboard infra runtimes: ${infra.join(', ')}\n`)
         }
-        // Memory slot (контракт «Слот памяти», 10.06): optional DEFAULT-YES install of
+        // Memory slot (контракт «Слот памяти»): optional DEFAULT-YES install of
         // the default provider; its own init runs with INHERITED stdio (the provider
         // owns the install questions). The step is REPORT-ONLY for the exit code — an
         // empty slot is a valid state regardless of why.
@@ -1354,9 +1354,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return 1
       }
       case 'start': {
-        // --all re-enables every REGISTERED peer (mirror of `stop --all` — the 11.06
-        // incident: bringing a stopped fleet back required a manual loop over ~25
-        // peers). Enumeration is the registry, so unregistered garbage (stray flag
+        // --all re-enables every REGISTERED peer (mirror of `stop --all` — without
+        // it, bringing a stopped fleet back required a manual loop over every
+        // peer). Enumeration is the registry, so unregistered garbage (stray flag
         // files for identities no record claims) is never touched. NOTE: for warm
         // peers this clears the stop flag only — no session is launched; each peer
         // becomes wakeable and the daemon brings its session up on the first message.
@@ -1390,13 +1390,13 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           if (o.codexHooksTrust) {
             out(`codex hooks trust: ${o.codexHooksTrust}\n`)
           }
-          // Stale identity-keyed markers must die with the record (boris 10.06: a
-          // namesake newborn inherited a dead peer's .stopped → refused to wake).
+          // Stale identity-keyed markers must die with the record (a namesake
+          // newborn inherited a dead peer's .stopped → refused to wake).
           if (o.purgedState?.length) {
             out(`lifecycle state purged: ${o.purgedState.join(', ')}\n`)
           }
           // Deliberate: the registry reap never deletes user data — but SAY so, or
-          // the default-location peers leave silent orphan folders (boris 10.06).
+          // the default-location peers leave silent orphan folders.
           if (o.cwd && existsSync(o.cwd)) {
             out(`folder kept: ${o.cwd} (remove never deletes peer data — \`rm -rf\` it yourself if it was a throwaway)\n`)
           }
@@ -1586,10 +1586,10 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return await runAlwaysOn(positionals[0], positionals[1], process.cwd())
       }
       case 'self-done': {
-        // SILENT-FINISH self-call for an ephemeral worker (контракт ЖЦ §wake_policy;
-        // развилка boris 10.06): a worker whose task produced NOTHING to send must
-        // still release its M3 FIFO — but an EMPTY report would violate Артур's
-        // invariant «событие-всё-отфильтровано = тишина» (no empty wakes of the
+        // SILENT-FINISH self-call for an ephemeral worker (контракт ЖЦ §wake_policy):
+        // a worker whose task produced NOTHING to send must still release its M3
+        // FIFO — but an EMPTY report would violate the invariant
+        // «событие-всё-отфильтровано = тишина» (no empty wakes of the
         // target). This verb is the non-waking arm: it sets the worker's OWN
         // .ephemeral-armed (same marker the ok-outbound hook sets), so the quiet
         // window reaps it within seconds and the drain feeds the next task — nobody
@@ -1610,10 +1610,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         setEphemeralArmed(cfg, identity)
         // The ephemeral check keys on the peer's CANONICAL cwd (registry), NOT on
         // process.cwd(): the verb is invoked from wherever the agent's shell
-        // happens to be (scriber lives in the vault half the time), and a foreign
-        // cwd made this warning LIE — «marker is inert» on a genuinely ephemeral
-        // peer (live case scriber 11.06: the false warning sent doc/scriber down a
-        // wrong root-cause chase). The marker itself was never affected — it is
+        // happens to be, and a foreign cwd made this warning LIE — «marker is
+        // inert» on a genuinely ephemeral peer (the false warning sends the reader
+        // down a wrong root-cause chase). The marker itself was never affected — it is
         // identity-keyed and supervise checks the SESSION's canonical cwd.
         const addr = parseSessionName(identity)!
         const canonicalCwd = findPeer(readPeersIndex({ env }), addr.personality)?.cwd ?? process.cwd()
@@ -1667,7 +1666,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return 0
       }
       case 'compact': {
-        // Dialogue control (UX directive 12.06): if the session is merely asleep
+        // Dialogue control: if the session is merely asleep
         // after a clean idle-reap, resume the same dialogue and compact it; if there
         // is no resumable dialogue, fail honestly instead of compacting a fresh one.
         if (!positionals[0]) return usage(errOut)
@@ -1736,36 +1735,8 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           return 1
         }
         out(`${r.woke ? 'woke + ' : ''}attaching ${r.identity}…\n`)
-        // Attach-window observability (killer-hunt 11.06: «была ли смерть под
-        // attach» was answerable only INDIRECTLY via wake cause=attach — i.e. only
-        // when the session was dead at attach time). Bracket the operator's client
-        // window in lifecycle.log: ev=attach at entry, ev=attach-end (with the tmux
-        // client's exit code) when the operator detaches or the server dies under
-        // the client. A death timestamp inside an attach…attach-end window now
-        // reads directly off the log.
         const attachCfg = loadLifecycleConfig(env)
-        appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach', identity: r.identity, woke: String(r.woke) }, { env })
-        // SPAWN-FLIP Ф0b-3: a supervisor-HOSTED session has no tmux to attach — hand the operator to
-        // the supervisor client (runSupervisorClient: raw passthrough + repaint-on-attach + Ctrl-]
-        // detach + both reattach port-deps). It calls process.exit on every terminal path, so bracket
-        // attach-end via an exit hook (appendFileSync is signal/exit-safe). Flag-off → tmux attach.
-        if (hostSessionAlive(r.identity)) {
-          process.on('exit', () =>
-            appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: process.exitCode ?? 0 }, { env }),
-          )
-          await runSupervisorClient(hostRunDir(), r.identity)
-          return 0 // unreachable — runSupervisorClient exits on detach / session end
-        }
-        // Drop the operator into the session. `env -u TMUX` so a nested attach from
-        // inside tmux does not error ("sessions should be nested with care").
-        const attachEnv = { ...env }
-        delete attachEnv.TMUX
-        const a = spawnSync('tmux', ['-S', r.socketPath, 'attach', '-t', r.identity], {
-          stdio: 'inherit',
-          env: attachEnv as Record<string, string>,
-        })
-        appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: a.status ?? -1 }, { env })
-        return a.status ?? 0
+        return await attachIntoSession(r.identity, r.socketPath, env, attachCfg.eventLogDir, r.woke)
       }
       case 'shadow': {
         // Read-only fidelity OBSERVER for the tmux→pty migration burn-in (track «b»). Compares
@@ -1824,14 +1795,25 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return await runSupervisorCli(rest)
       }
       default: {
-        // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh.
+        // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh. On a TTY this is
+        // the human "start a fresh session and work in it" verb (parallel to `attach`, which resumes):
+        // after a successful fresh bring-up it drops the operator straight into the new session.
+        // Non-TTY (scripted / piped) keeps the fire-and-forget behavior — report the launch and exit.
         if (verb && isRuntime(verb)) {
-          const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env })
+          const cfg = loadLifecycleConfig(env)
+          const id = resolveIdentity({ env })
+          const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env, cfg })
           if (r.status === 'FAILED') {
             errOut(`launch: ${r.reason}\n`)
             return 1
           }
-          out(`launched ${r.process_address} (fresh)\n`)
+          const identity = r.process_address ?? buildProcessAddress(verb, id.personality)
+          if (process.stdin.isTTY && process.stdout.isTTY) {
+            const socketPath = buildSocketPath(verb, id.personality, cfg.sockDir)
+            out(`launched ${identity} (fresh) — attaching…\n`)
+            return await attachIntoSession(identity, socketPath, env, cfg.eventLogDir, true)
+          }
+          out(`launched ${identity} (fresh)\n`)
           return 0
         }
         return usage(errOut)
@@ -1854,6 +1836,41 @@ function defaultFromIdentity(env: NodeJS.ProcessEnv): string {
   return resolveIdentity({ env }).address
 }
 
+/** Drop the operator into a live peer session — the interactive open shared by `attach` (resume)
+ *  and a TTY `iapeer <runtime>` (fresh launch). A supervisor-HOSTED session has no tmux to attach,
+ *  so the operator is handed to the supervisor client (raw passthrough + repaint-on-attach + Ctrl-]
+ *  detach); otherwise `tmux attach`. The operator window is bracketed in lifecycle.log
+ *  (ev=attach … ev=attach-end) so a death timestamp inside the window reads directly off the log.
+ *  Returns the client exit code. */
+async function attachIntoSession(
+  identity: string,
+  socketPath: string,
+  env: NodeJS.ProcessEnv,
+  eventLogDir: string,
+  woke: boolean,
+): Promise<number> {
+  appendLifecycleEvent(eventLogDir, { ev: 'attach', identity, woke: String(woke) }, { env })
+  if (hostSessionAlive(identity)) {
+    // runSupervisorClient calls process.exit on every terminal path → bracket attach-end via an
+    // exit hook (appendFileSync is signal/exit-safe).
+    process.on('exit', () =>
+      appendLifecycleEvent(eventLogDir, { ev: 'attach-end', identity, rc: process.exitCode ?? 0 }, { env }),
+    )
+    await runSupervisorClient(hostRunDir(), identity)
+    return 0 // unreachable — runSupervisorClient exits on detach / session end
+  }
+  // `env -u TMUX` so a nested attach from inside tmux does not error ("sessions should be nested
+  // with care").
+  const attachEnv = { ...env }
+  delete attachEnv.TMUX
+  const a = spawnSync('tmux', ['-S', socketPath, 'attach', '-t', identity], {
+    stdio: 'inherit',
+    env: attachEnv as Record<string, string>,
+  })
+  appendLifecycleEvent(eventLogDir, { ev: 'attach-end', identity, rc: a.status ?? -1 }, { env })
+  return a.status ?? 0
+}
+
 if (import.meta.main) {
   runCli(process.argv.slice(2)).then(code => process.exit(code))
 }

package/src/connect/index.ts

@@ -1,5 +1,5 @@
-// connect — per-peer channel attachment in ONE flow (design «Onboard костяка» §(в),
-// FINAL 10.06; flow facts confirmed by the telegram-runtime owner against v0.10.3).
+// connect — per-peer channel attachment in ONE flow (design «Onboard костяка» §(в);
+// flow facts confirmed by the telegram-runtime owner against v0.10.3).
 // Namespace: `iapeer connect <channel> <peer>` — extensible to future channels;
 // v1 implements `connect telegram <peer> [--token <t>]`.
 //
@@ -184,8 +184,8 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
     return { state: 'bot-add-failed', peer, detail: (add.stderr || add.stdout || `exit ${add.status}`).trim() }
   }
   // @username: the bots/<alias>/.env TELEGRAM_BOT_USERNAME field is the RELIABLE
-  // source (present on the live host; survives a quiet bot-add stdout — boris's
-  // acceptance saw the activation line degrade to the BotFather hint). stdout
+  // source (present on the live host; survives a quiet bot-add stdout — acceptance
+  // testing saw the activation line degrade to the BotFather hint). stdout
   // match stays as the fallback.
   const envAfterAdd = readBotEnv(alias, env)
   const envUser = envAfterAdd?.match(/^TELEGRAM_BOT_USERNAME=(.+)$/m)?.[1]?.trim()