@agfpd/iapeer 0.2.78 → 0.2.79

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.78",
+  "version": "0.2.79",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -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)
@@ -1735,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 (whether a death happened under 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
@@ -1823,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)
@@ -1853,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/supervisor/daemon.ts

@@ -1,12 +1,13 @@
 // Supervisor DAEMON — holds the pty + child + headless-xterm model + capability responder
-// independent of any terminal; clients attach/detach over a unix socket (cutover Block 2, ported
-// from the validated PoC pts.mjs). DARK: reachable only via the `supervisor` CLI verb (dynamic
-// import), so @xterm never loads in the delivery hot path. NOT wired into launch/lifecycle — it
-// serves NOTHING on the live fleet yet; it is validated on throwaway sessions only.
+// independent of any terminal; clients attach/detach over a unix socket. It HOSTS tui/router peers
+// by default (the pty-host launch path; opt-out per-peer via a `.no-pty-host` marker), and is also
+// reachable manually via the `supervisor` CLI verb for throwaway validation. It runs in its OWN
+// detached process, dynamic-imported from the launch path (supervisor/index.ts → daemon.ts), so
+// @xterm never loads in the central router's delivery path nor in the launch/lifecycle process.
 //
 // Loads @xterm/headless + @xterm/addon-serialize (the latter is the repaint source: a reattaching
 // client gets the full current screen even if the child is silent). Both bundle under
-// `bun build --compile` (pure JS; the Bun-native pty has no native addon — PoC-proven).
+// `bun build --compile` (pure JS; the Bun-native pty has no native addon).
 import { Terminal } from '@xterm/headless'
 import { SerializeAddon } from '@xterm/addon-serialize'
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'