@agfpd/iapeer 0.2.42 → 0.2.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/cli.test.ts

@@ -7,7 +7,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { formatListTable, listPeers, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
+import { formatListTable, listPeers, newPeer, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
 import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
 import { hasIdleReaped, isStopped, loadLifecycleConfig, setIdleReaped, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
@@ -397,3 +397,57 @@ describe('parseArgs (audit #27 — value beginning with --)', () => {
     expect(parseArgs(['x', '--description=']).flags.description).toBe('')
   })
 })
+
+// ─── new — the UNCONDITIONAL fresh-restart control (docs/Control-команды §new) ─
+
+describe('new (unconditional fresh restart)', () => {
+  test('happy path: fresh-slate (un-park + stale markers cleared) → fresh wake with resume:false task:"" → action fresh', async () => {
+    await register('alpha')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    // a parked peer with stale markers — /new must override ALL of it
+    setStopped(cfg, 'claude-alpha')
+    setIdleReaped(cfg, 'claude-alpha')
+    const calls: Array<{ personality: string; runtime: string; task: string; resume: boolean }> = []
+    const o = await newPeer('alpha', undefined, {
+      env: e,
+      wakeFn: async args => {
+        calls.push(args)
+        return { status: 'READY', woke: true, runtime: args.runtime, process_address: `${args.runtime}-${args.personality}`, taskDelivered: true }
+      },
+    })
+    expect(o.action).toBe('fresh')
+    expect(o.runtime).toBe('claude')
+    expect(calls).toEqual([{ personality: 'alpha', runtime: 'claude', task: '', resume: false }])
+    expect(isStopped(cfg, 'claude-alpha')).toBe(false) // un-parked: /new outranks the C1 stop
+    expect(hasIdleReaped(cfg, 'claude-alpha')).toBe(false) // stale marker cleared
+  })
+
+  test('wake FAILED → action failed with the reason (exit-1 contract for the bot)', async () => {
+    await register('beta2')
+    const o = await newPeer('beta2', undefined, {
+      env: env(),
+      wakeFn: async () => ({ status: 'FAILED', woke: false, reason: 'boot hang' }),
+    })
+    expect(o.action).toBe('failed')
+    expect(o.reason).toBe('boot hang')
+  })
+
+  test('refusals are explicit: foreign launchd / infra runtime / undeclared runtime / unknown peer', async () => {
+    const e = env()
+    // foreign PP plist → fleet guard
+    await register('boris')
+    writeFileSync(launchdPlistPath('boris', e), '<?xml version="1.0"?>\n<plist><dict><key>Label</key><string>com.iapeer.boris</string></dict></plist>\n')
+    expect((await newPeer('boris', undefined, { env: e })).action).toBe('refused-foreign-launchd')
+    // infra runtime → launchd-held, kickstart hint
+    await register('tg', 'telegram', 'natural')
+    const infra = await newPeer('tg', undefined, { env: e })
+    expect(infra.action).toBe('refused-infra')
+    expect(infra.reason).toContain('kickstart')
+    // undeclared runtime → explicit refusal, no silent launch
+    await register('gamma2')
+    expect((await newPeer('gamma2', 'codex', { env: e })).action).toBe('refused-undeclared-runtime')
+    // unknown peer → throws (same contract as stop/start)
+    await expect(newPeer('ghost-nobody', undefined, { env: e })).rejects.toThrow('not registered')
+  })
+})

package/src/cli/index.ts

@@ -27,6 +27,8 @@ import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../regist
 import { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
 import {
   attachPeer,
+  clearIdleReaped,
+  clearNewEager,
   clearStopped,
   folderLaunch,
   isLaunchdManaged,
@@ -41,6 +43,7 @@ import {
   setNewEager,
   setStopped,
   wakeOrSpawn,
+  type WakeResult,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
 import { isFoundationOwnedPlist, kickstartDaemon, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
@@ -269,6 +272,90 @@ export function startPeer(personality: string, runtime: string | undefined, opts
   return out
 }
 
+export interface NewPeerOutcome {
+  personality: string
+  runtime: string
+  action: 'fresh' | 'refused-foreign-launchd' | 'refused-infra' | 'refused-undeclared-runtime' | 'failed'
+  reason?: string
+}
+
+/**
+ * new <peer> [runtime] — the UNCONDITIONAL fresh-restart control command
+ * (docs/Control-команды §new; постановка boris 01:32 12.06, санкция Артура).
+ *
+ * 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
+ * `iapeer self-fresh`); a stuck/raving/dead peer never reads a prompt — this
+ * command restarts it MECHANICALLY, bypassing the peer entirely:
+ *   fresh-slate markers (un-park C1 stop, clear stale .idle-reaped/.new-eager) →
+ *   canary-clean teardown of any live session (killSession — a deliberate kill,
+ *   never a death class; session-state dropped so supervise stays silent) →
+ *   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
+ * 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
+ * leaves exactly one fresh live session (concurrent calls serialize on the
+ * wake lock). REFUSES foreign-launchd peers (fleet guard) and infra runtimes
+ * (launchd-held — their restart is `launchctl kickstart`'s domain), like
+ * stop/start; an explicitly-passed runtime the peer does not declare is an
+ * explicit refusal (never a silent launch of an undeclared runtime).
+ */
+export async function newPeer(
+  personality: string,
+  runtime: string | undefined,
+  opts: CliEnvOptions & { wakeFn?: (args: { personality: string; runtime: Runtime; task: string; resume: false }) => Promise<WakeResult> } = {},
+): Promise<NewPeerOutcome> {
+  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`)
+  if (isForeignLaunchd(personality, env)) {
+    return {
+      personality,
+      runtime: peer.runtime,
+      action: 'refused-foreign-launchd',
+      reason: `"${personality}" is managed by persistent-peer (foreign launchd plist) — the foundation does not restart it`,
+    }
+  }
+  if (runtime && !isRuntime(runtime)) throw new Error(`invalid runtime "${runtime}"`)
+  const rt: Runtime = (runtime as Runtime | undefined) ?? peer.runtime
+  if (!peer.runtimes.includes(rt)) {
+    return {
+      personality,
+      runtime: rt,
+      action: 'refused-undeclared-runtime',
+      reason: `peer "${personality}" does not declare runtime "${rt}" (declared: ${peer.runtimes.join(', ')})`,
+    }
+  }
+  if (isInfraRuntime(rt)) {
+    return {
+      personality,
+      runtime: rt,
+      action: 'refused-infra',
+      reason: `infra runtime "${rt}" is launchd-held — restart it with: launchctl kickstart -k gui/$(id -u)/${launchdLabel(personality)}`,
+    }
+  }
+  const identity = buildProcessAddress(rt, personality)
+  const sock = buildSocketPath(rt, personality, cfg.sockDir)
+  // Fresh slate: an explicit operator /new outranks a C1 park (it demands a live
+  // fresh session NOW) and any stale death/fresh markers (the wake below is fresh
+  // by construction — markers must not leak into a LATER wake's decision).
+  clearStopped(cfg, identity)
+  clearIdleReaped(cfg, identity)
+  clearNewEager(cfg, identity)
+  killSession(sock, identity) // canary-clean deliberate teardown; no-op when dead
+  removeSessionState(cfg, identity) // never a death class — supervise stays silent
+  const wake = opts.wakeFn ?? (args => wakeOrSpawn(args, { cfg, env }))
+  const r = await wake({ personality, runtime: rt, task: '', resume: false })
+  if (r.status !== 'READY') {
+    return { personality, runtime: rt, action: 'failed', reason: r.reason ?? 'wake failed' }
+  }
+  return { personality, runtime: rt, action: 'fresh' }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // remove — delete a peer's record from the registry through the LOCKED writer
 // (registry.removePeer). Direct edits of peers-profiles.json are refused at
@@ -565,6 +652,7 @@ const USAGE = `usage: iapeer <verb> [args]
   <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
   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)
   attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
   compact <peer> [runtime]                                       compact the peer's context (/compact)
@@ -948,6 +1036,20 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
         return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
       }
+      case 'new': {
+        // UNCONDITIONAL fresh restart (control, system class — docs/Control-команды
+        // §new): the emergency lever for a hung/dead session, bypasses the peer.
+        // Source: operator CLI, or telegram-runtime's clean-/new detect (their bot
+        // shells `iapeer new <peer> <runtime>` — exit 0 ⟺ fresh session up+ready).
+        if (!positionals[0]) return usage(errOut)
+        const o = await newPeer(positionals[0], positionals[1], { env })
+        if (o.action === 'fresh') {
+          out(`new: ${o.runtime}-${o.personality} fresh session up\n`)
+          return 0
+        }
+        errOut(`new: ${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        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

package/src/launch/adapters/codex.ts

@@ -319,11 +319,16 @@ export const codexAdapter: RuntimeAdapter = {
    *     interrupts the turn — NOT a double. (Codex's own footer says "esc to
    *     interrupt"; one Escape yields "■ Conversation interrupted". The contract's
    *     open "×1/×2?" is resolved to ×1, same as claude.) Session + context intact.
-   *   - compact → null (codex has no '/compact'; context management is its own).
+   *   - compact → type '/compact' then Enter. SNAPPED LIVE 12.06 (codex-cli
+   *     0.138.0): the slash EXISTS now — autocomplete documents it («summarize
+   *     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.
    *   - 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 }
     return null
   },
 }

package/src/launch/launch.test.ts

@@ -296,9 +296,10 @@ describe('executeControl (Ф-E control commands)', () => {
     expect(claudeAdapter.executeControl({ name: 'compact' })).toEqual({ sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 })
     expect(claudeAdapter.executeControl({ name: 'bogus' })).toBeNull()
   })
-  test('codex: interrupt → [Escape] (×1 baseline; ×2 snapped live); compact → null', () => {
+  test('codex: interrupt → [Escape] (×1, snapped live); compact → /compact + Enter (snapped live 12.06, codex-cli 0.138)', () => {
     expect(codexAdapter.executeControl({ name: 'interrupt' })).toEqual({ sequence: [['Escape']] })
-    expect(codexAdapter.executeControl({ name: 'compact' })).toBeNull()
+    expect(codexAdapter.executeControl({ name: 'compact' })).toEqual({ sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 })
+    expect(codexAdapter.executeControl({ name: 'bogus' })).toBeNull()
   })
   test('routers (telegram/notifier) refuse all control (no TUI turn)', () => {
     expect(telegramAdapter.executeControl({ name: 'interrupt' })).toBeNull()