axmap-cli 1.3.3 → 1.5.0

package/src/terminal-bridge.mjs

@@ -0,0 +1,225 @@
+/** The user launches an interactive CLI. axMap owns its PTY and a local,
+ * authenticated pipe; remote requests never launch/resume another model. */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import net from 'node:net'
+import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const validID = id => /^[0-9a-f-]{36}$/i.test(id || '')
+const sessionFile = id => {
+  if (!validID(id)) throw new Error('잘못된 터미널 세션 ID입니다.')
+  return path.join(bridgeHome(), 'sessions', `${id}.json`)
+}
+const pipeFor = id => process.platform === 'win32'
+  ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`)
+
+export function sendTerminal(id, message, token = null, { timeoutMs = 10000 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 응답 시간 한도가 필요합니다.')
+  const s = readJSON(sessionFile(id))
+  if (!['pty', 'stdio'].includes(s.transport)) throw new Error('로컬 관리형 세션이 아닙니다.')
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(pipeFor(id))
+    socket.setEncoding('utf8')
+    let buffer = ''
+    const fail = e => { socket.destroy(); reject(e) }
+    socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')))
+    socket.on('error', fail)
+    socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'))
+    socket.on('data', chunk => {
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > 1024 * 1024) return fail(new Error('로컬 응답 크기 제한 초과'))
+      const end = buffer.indexOf('\n')
+      if (end < 0) return
+      socket.end()
+      try {
+        const response = JSON.parse(buffer.slice(0, end))
+        if (response.error) reject(new Error(response.error)); else resolve(response.result)
+      } catch (e) { reject(e) }
+    })
+    socket.on('end', () => { if (!buffer.includes('\n')) reject(new Error('세션 연결이 응답 없이 종료됐습니다.')) })
+  })
+}
+
+export async function startTerminal({ executable, args = [], provider, cwd = process.cwd(), onData = () => {}, cols = 100, rows = 30 }) {
+  const { spawn } = await import('node-pty')
+  const id = randomUUID(), token = randomBytes(32).toString('hex')
+  const s = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
+    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' }
+  const jobs = new Map()
+  let pending = null, draft = false, term, closed = false, stopTimer
+  const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s) }
+  const finish = (state, result, error) => {
+    if (!pending) return
+    Object.assign(pending, { state, result, error, completedAt: new Date().toISOString() })
+    jobs.set(pending.id, { ...pending }); pending = null
+  }
+  const handle = message => {
+    const offered = Buffer.from(typeof message.token === 'string' ? message.token : '')
+    const expected = Buffer.from(token)
+    if (offered.length !== expected.length || !timingSafeEqual(offered, expected)) throw new Error('로컬 세션 인증 실패')
+    if (message.action === 'status') return { state: s.state, id, provider }
+    if (message.action === 'result') {
+      const job = jobs.get(message.id)
+      if (!job) throw new Error('이 터미널에 해당 요청이 없습니다.')
+      return job
+    }
+    if (message.action === 'hook') {
+      clearTimeout(stopTimer)
+      const { input, event } = message
+      s.event = event; s.model = input.modelName || input.model || s.model
+      s.conversationId = input.conversationId || input.session_id || s.conversationId
+      if (event !== 'Stop') {
+        s.state = 'running'; s.fullyIdle = false
+        if (pending && event === 'UserPromptSubmit' && typeof input.prompt === 'string') {
+          pending.observed = input.prompt.includes(`[axMap request ${pending.id}]`)
+        }
+        save(); return {}
+      }
+      if (provider === 'agy' && input.fullyIdle !== true) { save(); return {} }
+      let answer = input.last_assistant_message
+      if (provider === 'agy') {
+        const log = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'),
+          'brain', s.conversationId || '', '.system_generated', 'logs', 'transcript.jsonl')
+        if (path.resolve(input.transcriptPath || '') !== log) throw new Error('종료 훅의 대화 기록 경로가 다릅니다.')
+        const lines = fs.readFileSync(log, 'utf8').trimEnd().split('\n').filter(Boolean).map(line => JSON.parse(line))
+        const lastUser = lines.findLast(e => e.type === 'USER_INPUT')
+        if (pending) pending.observed = String(lastUser?.content).includes(`[axMap request ${pending.id}]`)
+        answer = lines.findLast(e => e.type === 'PLANNER_RESPONSE' && e.source === 'MODEL' && e.status === 'DONE')?.content
+      }
+      if (pending) finish(pending.observed && !pending.interrupted && typeof answer === 'string' ? 'completed' : 'superseded',
+        pending.observed && !pending.interrupted ? answer : undefined,
+        pending.observed && !pending.interrupted ? undefined : '다른 입력이 섞였거나 이 요청의 응답을 확인하지 못했습니다.')
+      // Stop runs before the provider restores its input UI. Allow that handoff
+      // to finish before accepting another injected prompt.
+      s.state = 'settling'; s.fullyIdle = false; save()
+      stopTimer = setTimeout(() => { if (!closed && s.state === 'settling') { s.state = 'idle'; s.fullyIdle = true; draft = false; save() } }, 500)
+      return {}
+    }
+    if (message.action === 'submit') {
+      const request = message.request
+      if (closed || s.state !== 'idle' || draft || pending) throw new Error('상대가 대기 중이 아니거나 입력 중입니다. 작업을 전달하지 않았습니다.')
+      if (!validID(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768) throw new Error('요청 형식이 올바르지 않습니다.')
+      const prompt = `[axMap request ${request.id}]\n요청자: ${String(request.from || 'axmap')}\n${request.prompt}`
+      if (/[\x00-\x08\x0b-\x1f\x7f]/.test(prompt)) throw new Error('터미널 제어 문자가 포함된 요청은 보낼 수 없습니다.')
+      pending = { id: request.id, to: id, state: 'submitted' }; jobs.set(request.id, pending)
+      s.state = 'running'; s.fullyIdle = false; save()
+      term.write(`\x1b[200~${prompt}\x1b[201~`)
+      setTimeout(() => { if (!closed) term.write('\r') }, 100)
+      return { accepted: true, session: id }
+    }
+    throw new Error('지원하지 않는 로컬 세션 요청입니다.')
+  }
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 })
+  const server = net.createServer(socket => {
+    socket.setEncoding('utf8')
+    let buffer = '', handled = false
+    socket.setTimeout(15000, () => socket.destroy())
+    socket.on('error', () => {})
+    socket.on('data', chunk => {
+      if (handled) return
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > 65536) return socket.destroy()
+      const end = buffer.indexOf('\n'); if (end < 0) return
+      handled = true
+      try { socket.end(JSON.stringify({ result: handle(JSON.parse(buffer.slice(0, end))) }) + '\n') }
+      catch (e) { socket.end(JSON.stringify({ error: e.message }) + '\n') }
+    })
+  })
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(pipeFor(id), resolve) })
+  if (process.platform !== 'win32') fs.chmodSync(pipeFor(id), 0o600)
+  save()
+  try {
+    term = spawn(executable, args, { name: 'xterm-256color', cols, rows, cwd, env: { ...process.env,
+      AXMAP_TERMINAL_SESSION: id, AXMAP_TERMINAL_TOKEN: token,
+      AXMAP_AGENT: `${provider}-${id.slice(0, 8)}`, AXMAP_SESSION: id,
+    }, useConpty: true, useConptyDll: process.platform === 'win32' })
+  } catch (e) { server.close(); s.state = 'closed'; save(); throw e }
+  term.onData(onData)
+  const exited = new Promise(resolve => term.onExit(ev => {
+    if (closed) return
+    closed = true; clearTimeout(stopTimer)
+    // ConPTY may keep its input handle alive after a normal child exit.
+    if (process.platform === 'win32') { try { term.kill() } catch { /* already closed */ } }
+    finish('unknown', undefined, '요청의 완료를 확인하기 전에 세션이 종료됐습니다.')
+    s.state = 'closed'; s.fullyIdle = false; save(); server.close(); resolve(ev)
+  }))
+  return { id, pid: term.pid, exited,
+    input(data) {
+      const terminalReply = /^\x1b\[(?:\d+;\d+R|\?[^a-zA-Z]*[a-zA-Z])$/.test(String(data))
+      if (terminalReply) { term.write(data); return }
+      if (pending) pending.interrupted = true
+      draft = !String(data).includes('\r')
+      if (!draft) { s.state = 'running'; s.fullyIdle = false; save() }
+      term.write(data)
+    },
+    resize: (c, r) => term.resize(c, r),
+    close: () => term.kill(),
+  }
+}
+
+/** Copy only production dependencies from the npm package, not a developer's
+ * entire node_modules. This also keeps the setup copy independent of npm cache. */
+export function installTerminalRuntime(sourceRoot, destRoot = ROOT) {
+  const source = path.resolve(sourceRoot), dest = path.resolve(destRoot)
+  const require = createRequire(path.join(source, 'package.json'))
+  const copied = new Set()
+  function copy(name) {
+    if (copied.has(name)) return
+    const descriptor = require.resolve(`${name}/package.json`)
+    const pkg = readJSON(descriptor)
+    const target = path.join(dest, 'node_modules', ...name.split('/'))
+    if (path.resolve(path.dirname(descriptor)) !== path.resolve(target)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.cpSync(path.dirname(descriptor), target, { recursive: true, force: true })
+    }
+    copied.add(name)
+    for (const dependency of Object.keys(pkg.dependencies || {})) copy(dependency)
+    for (const dependency of Object.keys(pkg.optionalDependencies || {})) {
+      try { require.resolve(`${dependency}/package.json`) }
+      catch (e) { if (e.code === 'MODULE_NOT_FOUND') continue; throw e }
+      copy(dependency)
+    }
+  }
+  copy('node-pty')
+  const installed = createRequire(path.join(dest, 'package.json'))('node-pty')
+  if (typeof installed.spawn !== 'function') throw new Error('설치된 터미널 라이브러리를 불러오지 못했습니다.')
+  return { packages: [...copied], destination: dest }
+}
+
+export function installTerminalHooks(home = os.homedir(), provider = 'agy') {
+  if (!['agy', 'codex'].includes(provider)) throw new Error('지원하지 않는 CLI 훅입니다.')
+  const target = provider === 'agy' ? path.join(home, '.gemini', 'config', 'hooks.json')
+    : path.join(home, '.codex', 'hooks.json')
+  const config = fs.existsSync(target) ? readJSON(target) : {}
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('기존 hooks.json을 읽지 못했습니다.')
+  if (provider === 'codex' && config.hooks !== undefined && (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks))) throw new Error('기존 Codex hooks 설정이 객체가 아닙니다.')
+  const definition = {}
+  const script = path.join(ROOT, 'tools', 'run.mjs')
+  if ([process.execPath, script].some(p => /["\r\n%&|<>^]/.test(p))) throw new Error('훅 경로에 지원하지 않는 셸 문자가 있습니다.')
+  for (const event of provider === 'agy' ? ['SessionStart', 'PreInvocation', 'Stop'] : ['SessionStart', 'UserPromptSubmit', 'Stop']) {
+    let command = `"${process.execPath}" "${script}" hook ${event}`
+    if (process.platform === 'win32') {
+      const wrapper = path.join(home, '.axmap', 'bridge', `terminal-${provider}-${event}.cmd`)
+      if (/[\s"%&|<>^]/.test(wrapper)) throw new Error('이 Windows 훅 경로에는 공백/셸 문자를 사용할 수 없습니다.')
+      fs.mkdirSync(path.dirname(wrapper), { recursive: true })
+      fs.writeFileSync(wrapper, `@echo off\r\n${command}\r\n`)
+      command = wrapper
+    }
+    if (provider === 'agy') definition[event] = [{ type: 'command', command, timeout: 10 }]
+    else {
+      config.hooks ||= {}
+      const existing = config.hooks[event] || []
+      if (!Array.isArray(existing)) throw new Error(`기존 Codex ${event} 설정이 배열이 아닙니다.`)
+      config.hooks[event] = existing.filter(group => !(Array.isArray(group.hooks) && group.hooks.some(h => h.statusMessage === 'axMap terminal bridge')))
+      config.hooks[event].push({ hooks: [{ type: 'command', command, timeout: 10, statusMessage: 'axMap terminal bridge' }] })
+    }
+  }
+  if (provider === 'agy') config['axmap-terminal'] = definition
+  writeJSON(target, config)
+  return target
+}

package/src/update.mjs

@@ -28,7 +28,7 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
-import { stateDir } from './repotarget.mjs'
+import { stateDir } from './state.mjs'
 
 /**
  * 꾸러미 이름. **`package.json` 의 `name` 과 반드시 같아야 한다.**

package/tools/bridge.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import { resolveBin } from '../src/agentcli.mjs'
+import { codexInvocation } from './mcp-register.mjs'
+import { dispatchRequest, installHooks, registerHook, requestResult, sessions, uninstallHooks } from '../src/bridge.mjs'
+import { startManagedSession } from '../src/managed-session.mjs'
+import { runDialogue, startBackgroundDialogue, dialogueResult, stopDialogue } from '../src/session-dialogue.mjs'
+import { sendTerminal } from '../src/terminal-bridge.mjs'
+import { sessionStatus, formatSessionStatus } from '../src/session-status.mjs'
+import { attachConsole } from '../src/external-console.mjs'
+
+const args = process.argv.slice(2)
+const [command] = args
+const option = (name) => { const i = args.indexOf(`--${name}`); return i < 0 ? undefined : args[i + 1] }
+const output = (value) => console.log(JSON.stringify(value, null, 2))
+try {
+  switch (command) {
+    case 'attach': output(attachConsole({ pid: Number(option('pid')), cwd: process.cwd() })); break
+    case 'serve': {
+      const provider = args[1]
+      if (!['codex', 'agy'].includes(provider)) throw new Error('axmap bridge serve codex|agy를 사용하세요.')
+      const binary = resolveBin(provider)
+      if (!binary) throw new Error(`${provider} 실행 파일을 찾지 못했습니다.`)
+      const [executable, ...prefix] = provider === 'codex' ? codexInvocation(binary) : [binary]
+      const session = await startManagedSession({ provider, executable, prefix, model: option('model'), role: option('role'),
+        maxTokens: Number(option('max-tokens') || 100000), onEvent: output })
+      output({ event: 'connected', ...session, exited: undefined, close: undefined })
+      process.once('SIGINT', session.close); process.once('SIGTERM', session.close)
+      const exit = await session.exited
+      process.exitCode = exit.code || 0
+      break
+    }
+    case 'chat': {
+      const options = { ...(option('id') ? { id: option('id') } : {}), left: option('left'), right: option('right'), prompt: fs.readFileSync(0, 'utf8'),
+        maxTurns: Number(option('max-turns') || 4), maxTokens: Number(option('max-tokens') || 50000),
+        maxMessageChars: Number(option('max-message-chars') || 2000),
+        onEvent: event => console.error(JSON.stringify(event)) }
+      const r = args.includes('--background') ? await startBackgroundDialogue(options) : await runDialogue(options)
+      output(r); if (r.state !== 'completed') process.exitCode = 2
+      if (r.state === 'queued') process.exitCode = 0
+      break
+    }
+    case 'dialogue': output(dialogueResult(args[1])); break
+    case 'stop': output(stopDialogue(args[1])); break
+    case 'answer': output(await sendTerminal(option('to'), { action: 'answer', id: option('request'), decision: option('decision') })); break
+    case 'install':
+      if (!args.includes('--experimental')) throw new Error('실험용 연결입니다. 현재 검증한 CLI는 필요한 연결 정보를 훅에 제공하지 않습니다. 확인 후 --experimental로 명시하세요.')
+      output(installHooks({ executable: option('executable') })); break
+    case 'uninstall': output(uninstallHooks()); break
+    case 'hook': {
+      const input = JSON.parse(fs.readFileSync(0, 'utf8'))
+      try {
+        registerHook(input, option('event'), { ...process.env, AXMAP_AGY_EXECUTABLE: option('executable') })
+      } catch (e) { console.error(`axMap bridge: ${e.message}`) }
+      // Observe only. Never alter a provider's permission or continuation decision.
+      output({})
+      break
+    }
+    case 'sessions': output(sessions(process.cwd())); break
+    case 'status': {
+      const listed = await sessionStatus()
+      if (args.includes('--json')) output(listed)
+      else console.log(formatSessionStatus(listed))
+      break
+    }
+    case 'send': {
+      const r = dispatchRequest({ to: option('to'), prompt: fs.readFileSync(0, 'utf8'), cwd: process.cwd(), from: process.env.AXMAP_AGENT || 'axmap' })
+      output(r)
+      if (r.state === 'unknown') process.exitCode = 2
+      break
+    }
+    case 'result': output(requestResult(args[1], process.cwd())); break
+    case undefined:
+    case '--help':
+      console.log(`axMap 로컬 세션 연결 — 관리형 Codex/agy와 제한된 자동 대화
+axmap bridge serve codex|agy [--model 이름] [--role 역할] [--max-tokens 100000]
+    명시적으로 새 관리형 CLI를 시작합니다. 기존 창에 임의로 붙지 않습니다.
+axmap bridge chat --left <UUID> --right <UUID> [--max-turns 4] [--max-tokens 50000]
+    stdin 작업을 자동 중계합니다. 기본 메시지 한도 2000자, 대기 중 모델 호출 없음.
+axmap bridge answer --to <UUID> --request <ID> --decision accept|decline|cancel
+    Codex가 요청한 이번 실행의 승인을 사용자가 결정합니다.
+axmap bridge chat ... --background                  접수 ID를 반환하고 백그라운드 중계
+axmap bridge dialogue <대화 UUID>                    상태·회신·누적 토큰 조회
+axmap bridge stop <대화 UUID>                        추가 중계 중단 (이미 보낸 요청은 계속될 수 있음)
+axmap bridge install --experimental --executable <agy 절대 경로>   연결 훅 실험
+axmap bridge uninstall                             추가한 연결 훅 해제
+axmap bridge sessions                              이 repo에 연결된 세션
+axmap bridge attach --pid <PID>                    이미 실행한 Windows agy 콘솔을 현재 repo에 연결
+axmap bridge status [--json]                        로컬 연결·작업·승인 대기·종료 상태 조회 (모델 호출 없음)
+axmap bridge send --to <세션 UUID>                  본문은 stdin. 기존 세션에 전달
+axmap bridge result <요청 UUID>                     제출/완료/불명 상태와 결과
+관리형 stdio: Codex App Server / agy stream-json. PTY와 agentapi는 별도 실험 경로입니다.`)
+      break
+    default: throw new Error(`알 수 없는 bridge 명령: ${command}`)
+  }
+} catch (e) { console.error(e.message); process.exitCode = 1 }

package/tools/mcp-register.mjs

@@ -30,7 +30,7 @@
  *
  * ── 감지는 새로 짜지 않는다 ───────────────────────────────────────────────
  *
- * 어떤 CLI 가 이 PC 에 있는지는 `app/lib/agentcli.mjs` 가 이미 안다(`AGENTS`, `resolveBin`).
+ * 어떤 CLI 가 이 PC 에 있는지는 `src/agentcli.mjs` 가 이미 안다(`AGENTS`, `resolveBin`).
  * 거기서 그대로 가져온다. 바이너리 이름이 두 군데에 적히면 한쪽만 낡는다.
  */
 
@@ -40,7 +40,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { AGENTS, resolveBin } from '../app/lib/agentcli.mjs'
+import { AGENTS, resolveBin } from '../src/agentcli.mjs'
 import { claudeUserEntry } from '../src/mcpstate.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))

package/tools/run-tests.mjs

@@ -37,6 +37,13 @@ if (files.length === 0) {
   process.exit(1)
 }
 
-const r = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit', cwd: root })
-// status 가 null 이면 신호로 죽은 것이다. 통과로 세지 않는다.
-process.exit(r.status ?? 1)
+// Windows ConPTY owns native console workers. Exercise it after other test
+// processes have exited so temporary console teardown cannot race the suite's
+// many concurrent subprocess fixtures. Both batches remain mandatory.
+const native = process.platform === 'win32' ? files.filter(f => path.basename(f) === 'terminal-bridge.test.mjs') : []
+const ordinary = files.filter(f => !native.includes(f))
+for (const batch of [ordinary, native].filter(batch => batch.length)) {
+  const r = spawnSync(process.execPath, ['--test', ...batch], { stdio: 'inherit', cwd: root })
+  if (r.status !== 0) process.exit(r.status ?? 1)
+}
+process.exit(0)

package/tools/run.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { startTerminal, sendTerminal, installTerminalHooks, installTerminalRuntime } from '../src/terminal-bridge.mjs'
+import { registerExternalHook } from '../src/external-console.mjs'
+
+const [command, ...args] = process.argv.slice(2)
+try {
+  if (command === 'install-runtime') {
+    console.log(JSON.stringify(installTerminalRuntime(args[0])))
+  } else if (command === 'install-hooks') {
+    console.log(JSON.stringify({ hooks: [installTerminalHooks(), installTerminalHooks(undefined, 'codex')] }))
+  } else if (command === 'rpc') {
+    console.log(JSON.stringify(await sendTerminal(args[0], JSON.parse(fs.readFileSync(0, 'utf8')))))
+  } else if (command === 'hook') {
+    const input = JSON.parse(fs.readFileSync(0, 'utf8'))
+    if (process.env.AXMAP_TERMINAL_SESSION && process.env.AXMAP_TERMINAL_TOKEN) {
+      await sendTerminal(process.env.AXMAP_TERMINAL_SESSION, { action: 'hook', event: args[0], input }, process.env.AXMAP_TERMINAL_TOKEN)
+    } else if (process.platform === 'win32' && input.conversationId) {
+      try { registerExternalHook(input, args[0]) }
+      catch (e) { console.error(`axMap 독립 콘솔: ${e.message}`) }
+    }
+    console.log('{}')
+  } else if (command === '--help' || !command) {
+    console.log('axmap run agy|codex [기존 CLI 인수...] [--cwd 작업폴더]\n사용자가 여는 실제 CLI 터미널을 유지합니다. 별도 연결 URL은 필요 없습니다.')
+  } else {
+    if (!['agy', 'codex'].includes(command)) throw new Error('현재 실행 도구는 agy 또는 codex입니다.')
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('사용자가 연 대화형 터미널에서 실행하세요. 새 백그라운드 AI 세션은 만들지 않습니다.')
+    const cwdAt = args.indexOf('--cwd')
+    let cwd = process.cwd()
+    if (cwdAt >= 0) {
+      if (!args[cwdAt + 1]) throw new Error('--cwd 뒤에 작업 폴더를 지정하세요.')
+      cwd = path.resolve(args[cwdAt + 1]); args.splice(cwdAt, 2)
+    }
+    const found = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', [command], { encoding: 'utf8', windowsHide: true })
+    const executable = found.stdout?.split(/\r?\n/).map(s => s.trim()).find(s => s && (process.platform !== 'win32' || path.extname(s).toLowerCase() === '.exe'))
+    if (!executable) throw new Error(`${command} 실행 파일을 찾지 못했습니다.`)
+    installTerminalHooks(undefined, command)
+    if (command === 'codex') console.error('Codex가 새 훅의 신뢰 확인을 요청하면 /hooks에서 axMap 훅을 검토하세요. 승인을 자동으로 우회하지 않습니다.')
+    let terminal
+    const oldRaw = process.stdin.isRaw
+    try {
+      terminal = await startTerminal({ executable, args, provider: command, cwd, cols: process.stdout.columns || 100, rows: process.stdout.rows || 30, onData: data => process.stdout.write(data) })
+      console.error(`axMap 연결 세션: ${terminal.id}`)
+      process.stdin.setRawMode(true); process.stdin.resume()
+      const input = data => terminal.input(data.toString('utf8'))
+      const resize = () => terminal.resize(process.stdout.columns || 100, process.stdout.rows || 30)
+      process.stdin.on('data', input); process.stdout.on('resize', resize)
+      const stop = () => terminal.close()
+      process.once('SIGTERM', stop)
+      const ev = await terminal.exited
+      process.removeListener('SIGTERM', stop)
+      process.stdin.off('data', input); process.stdout.off('resize', resize)
+      process.exitCode = ev.exitCode
+    } finally {
+      process.stdin.setRawMode(oldRaw); process.stdin.pause()
+      process.stdout.write('\x1b[?2004l\x1b[?25h')
+    }
+    // node-pty's Windows output worker can outlive the exited console. This
+    // standalone terminal host has finished; release its remaining native handles.
+    process.exit(process.exitCode || 0)
+  }
+} catch (e) { console.error(e.message); process.exitCode = 1 }

package/tools/setup.mjs

@@ -251,6 +251,17 @@ function installAndRegister() {
 
 installAndRegister()
 
+// The installed copy owns stable hook paths, including the bundled PTY runtime.
+if (!has('--no-register')) {
+  if (DRY) hm('세션 연결', '(dry-run) 설치된 사본에 CLI 연결 훅을 등록합니다')
+  else {
+    const hookRunner = path.join(DEST, 'tools', 'run.mjs')
+    const r = spawnSync(process.execPath, [hookRunner, 'install-hooks'], { encoding: 'utf8', windowsHide: true })
+    if (r.status === 0) ok('세션 연결', 'Windows에서 직접 여는 agy와 axmap run CLI가 자동 연결됩니다')
+    else no('세션 연결', r.stderr?.trim() || '연결 훅 등록 실패')
+  }
+}
+
 // ── 6. 장부와 훅 ────────────────────────────────────────────────────────────
 //
 // 🔴 **설치된 사본**(`~/.axmap/app`)의 CLI 로 부른다. npx 가 푼 임시 폴더의 것으로

package/tools/windows-console.ps1

@@ -0,0 +1,91 @@
+param([int]$TargetPid, [string]$Action = 'snapshot')
+$ErrorActionPreference = 'Stop'
+$utf8 = New-Object System.Text.UTF8Encoding($false)
+[Console]::InputEncoding = $utf8
+[Console]::OutputEncoding = $utf8
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+# Keep the original pipe writer: AttachConsole replaces the standard handles.
+$reply = [Console]::Out
+if ($Action -eq 'ancestor') {
+ for ($i = 0; $i -lt 12 -and $TargetPid -gt 0; $i++) {
+  $entry = Get-CimInstance Win32_Process -Filter "ProcessId=$TargetPid"
+  if (!$entry) { break }
+  if ($entry.Name -eq 'agy.exe') {
+   if ($entry.CommandLine -match '--input-format|--print(?:\s|=|$)|(?:^|\s)-p(?:\s|$)') { $reply.WriteLine('{"ignored":true}'); exit 0 }
+   $proc = Get-Process -Id $TargetPid
+   $reply.WriteLine((@{ pid=$TargetPid; startedAt=$proc.StartTime.ToUniversalTime().ToString('o') } | ConvertTo-Json -Compress))
+   exit 0
+  }
+  $TargetPid = $entry.ParentProcessId
+ }
+ throw 'No interactive agy ancestor found'
+}
+Add-Type -TypeDefinition @'
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+using System.ComponentModel;
+public static class AxConsole {
+ [StructLayout(LayoutKind.Sequential)] public struct Coord { public short X,Y; }
+ [StructLayout(LayoutKind.Sequential)] public struct Rect { public short Left,Top,Right,Bottom; }
+ [StructLayout(LayoutKind.Sequential)] public struct Info { public Coord Size,Cursor; public short Attr; public Rect Window; public Coord Max; }
+ [StructLayout(LayoutKind.Explicit, CharSet=CharSet.Unicode, Size=20)] public struct Record {
+  [FieldOffset(0)] public short Type;
+  [FieldOffset(4)] public int Down;
+  [FieldOffset(8)] public short Repeat;
+  [FieldOffset(10)] public short Key;
+  [FieldOffset(14)] public char Char;
+ }
+ [DllImport("kernel32.dll", SetLastError=true)] static extern bool AttachConsole(uint pid);
+ [DllImport("kernel32.dll")] public static extern bool FreeConsole();
+ [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern IntPtr CreateFile(string name,uint access,uint share,IntPtr sec,uint mode,uint flags,IntPtr template);
+ [DllImport("kernel32.dll", SetLastError=true)] static extern bool GetConsoleScreenBufferInfo(IntPtr h,out Info info);
+ [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern bool ReadConsoleOutputCharacter(IntPtr h,[Out] char[] text,uint count,Coord at,out uint read);
+ [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern bool WriteConsoleInput(IntPtr h,Record[] input,uint count,out uint written);
+ [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr h);
+ static void Check(bool ok) { if(!ok) throw new Win32Exception(Marshal.GetLastWin32Error()); }
+ public static void Attach(int pid) { FreeConsole(); Check(AttachConsole((uint)pid)); }
+ static IntPtr Open(string name) { var h=CreateFile(name,0xC0000000,3,IntPtr.Zero,3,0,IntPtr.Zero); if(h==new IntPtr(-1)) throw new Win32Exception(Marshal.GetLastWin32Error()); return h; }
+ public static string Snapshot() {
+  var h=Open("CONOUT$"); try {
+   Info info; Check(GetConsoleScreenBufferInfo(h,out info));
+   var text=new StringBuilder();
+   for(short y=info.Window.Top;y<=info.Window.Bottom;y++) {
+    uint read; var row=new char[info.Size.X]; Check(ReadConsoleOutputCharacter(h,row,(uint)row.Length,new Coord { X=0,Y=y },out read)); text.AppendLine(new string(row,0,(int)read).TrimEnd());
+   }
+   return text.ToString();
+  } finally { CloseHandle(h); }
+ }
+ public static void Send(string text) {
+  var h=Open("CONIN$"); try {
+   var records=new Record[text.Length*2];
+   for(int i=0;i<text.Length;i++) {
+    var r=new Record {Type=1,Down=1,Repeat=1,Char=text[i],Key=(short)(text[i]=='\r'?13:0)};
+    records[i*2]=r; r.Down=0; records[i*2+1]=r;
+   }
+   uint written; Check(WriteConsoleInput(h,records,(uint)records.Length,out written));
+   if(written!=records.Length) throw new Exception("Partial console delivery; do not retry automatically.");
+  } finally { CloseHandle(h); }
+ }
+}
+'@
+try {
+ $proc = Get-Process -Id $TargetPid
+ if ($proc.ProcessName -ne 'agy') { throw 'Target is not agy.exe' }
+ $commandLine = (Get-CimInstance Win32_Process -Filter "ProcessId=$TargetPid").CommandLine
+ if ($commandLine -match '--input-format|--print(?:\s|=|$)|(?:^|\s)-p(?:\s|$)') { throw 'Target is not an interactive agy console' }
+ if ($payload.startedAt -and $proc.StartTime.ToUniversalTime().ToString('o') -ne $payload.startedAt) { throw 'Process identity changed' }
+ [AxConsole]::Attach($TargetPid)
+ $screen = [AxConsole]::Snapshot()
+ if ($Action -eq 'send') {
+  if ($payload.expectedScreen -cne $screen) { throw 'Console changed before delivery; input was not sent' }
+  [AxConsole]::Send($payload.text)
+ }
+ $result = @{ screen = $screen; startedAt = $proc.StartTime.ToUniversalTime().ToString('o'); pid = $TargetPid }
+ [AxConsole]::FreeConsole() | Out-Null
+ $reply.WriteLine(($result | ConvertTo-Json -Compress))
+} catch {
+ [AxConsole]::FreeConsole() | Out-Null
+ $reply.WriteLine((@{ error = $_.Exception.Message } | ConvertTo-Json -Compress))
+ exit 1
+}