@dmsdc-ai/aigentry-telepty 0.1.98 → 0.3.5

package/docs/superpowers/specs/2026-05-02-submit-force-and-retry.md

@@ -0,0 +1,139 @@
+# 2026-05-02 — `inject --submit-force` + idempotent client retry
+
+Closes task #347 (telepty 0.3.2 `--submit` prompt-symbol gate reliability —
+context-ref inject arrived at orchestrator but Enter was skipped when the
+input area had a transient render mismatch: autocomplete dropdown open,
+cursor moved, mid-render race).
+
+## Problem
+
+`telepty inject --submit` runs three layers of gating before pressing
+Enter:
+
+| Layer | File | Trigger | Skip behavior |
+|---|---|---|---|
+| 3. Prompt-symbol (0.3.2) | `src/submit-gate.js` `awaitPromptSymbol` | `cmux read-screen` does not show the per-CLI prompt symbol stably for ≥200 ms within 8 s | Falls through to Layer 1 (`no_prompt_symbol_seen`) |
+| 1. State-gated (0.3.1) | `src/submit-gate.js` `awaitReplReady` | `sessionStateManager` is not in `idle`/`waiting` with conf ≥ 0.5 within 10 s | Best-effort dispatch on `timeout`; hard-fail short-circuits to 504 on `session_dead`/`error`/`restarting`/`no_state` |
+| Verify | `src/submit-gate.js` `verifyBodyConsumed` | Injected body still visible in `outputRing` after dispatch | One bounded retry; if still visible, 504 with `reason: 'gated_dispatch_unconsumed'` |
+
+In production this still produces a residual failure rate when the
+orchestrator session has a transient render mismatch (autocomplete drop-down,
+cursor outside input area, mid-paste). The body is injected, the gate times
+out, the dispatch fires Enter into a "wrong" focus, and `verifyBodyConsumed`
+correctly sees the body still in the input box → 504. Sub-sessions then
+print `⚠️ Submit gated-timeout` and the human user has to press Enter
+manually for the orchestrator to consume the inject.
+
+## Constraints
+
+- **Article 1 (경량)**: minimum-touch fix. No new modules, no new daemon
+  endpoint, no new helper module.
+- **Article 17 (무의존)**: no new runtime dependency.
+- **Article 9 (독립)**: telepty must keep working standalone (no cmux/kitty
+  required for the new flags).
+- **Backward compat**: existing `--submit` semantics unchanged. Default
+  `--submit-retry` value MUST be 0-effect on the happy path (which is the
+  vast majority of calls, currently shipping reliably).
+- **Idempotency**: a retry must never double-press Enter.
+
+## Approach
+
+Two opt-in CLI knobs on `telepty inject`, both implemented client-side
+in `cli.js`. Daemon `/submit` endpoint is untouched — `force: true` is
+already supported (introduced in 0.3.1 for `telepty send-key`); we just
+plumb it through from the inject path.
+
+### `--submit-force`
+
+Adds `force: true` to the `/submit` POST body. Daemon-side this skips
+both Layer 3 (prompt-symbol) and Layer 1 (state-gate) and dispatches Enter
+once via the existing `terminalLevelSubmit` chain (kitty → cmux → PTY).
+
+Use case: caller is confident the target REPL is ready (e.g., orchestrator
+visibly idle, or Phase-6 cascade where sub-session has just verified the
+orchestrator's last bus event). Mirrors the existing `telepty send-key`
+escape hatch but at the inject level so a single command does both.
+
+### `--submit-retry N` (default 1, clamp [0, 3])
+
+After a 504 from `/submit` with a **retry-safe** reason, wait 300 ms and
+re-issue the same `/submit` request up to N times. Retry-safe reasons:
+
+| Reason | Source | Why retry is idempotent |
+|---|---|---|
+| `gated_dispatch_unconsumed` | `daemon.js:1680` | The verify path saw the body STILL in the input box after best-effort dispatch. Re-firing Enter when the body is visibly un-consumed cannot double-submit. |
+| `gate_timeout` | `awaitReplReady` returning `timeout` (no longer reaches 504 directly in 0.3.1, but kept for forward-compat) | Same: body has not been consumed if we're still on the gated path. |
+| `no_prompt_symbol_seen` | `awaitPromptSymbol` Layer 3 timeout (also not currently a 504 source, but kept for forward-compat) | Layer 3 alone never emits 504 today. Listed for completeness. |
+
+Retry is **explicitly NOT** safe for hard-fail reasons — `session_dead`,
+`session_error`, `session_restarting`, `no_state`, `no_state_manager`. Those
+short-circuit the loop immediately because re-firing won't recover. Same
+for any non-504 status (4xx) — no point retrying a malformed request.
+
+The retry preserves the original flag set (`force` stays `force`, etc.).
+The `attemptsMade` counter is rendered into the success line as
+`[retry K/N]` so operators can see when the retry path actually fired.
+
+### Why client-side (not daemon-side)?
+
+- Server-side already retries once internally inside `verifyBodyConsumed`
+  (`daemon.js:1663-1672`). Adding a second loop server-side conflates two
+  feedback signals (the inner verify retry vs. the outer client retry) in
+  one response shape.
+- Per-call client control is more flexible — sub-sessions that have
+  cheap evidence of orchestrator readiness can pass `--submit-retry 0`
+  to avoid the extra round-trip; ones that don't can pass `--submit-retry 2`.
+- Keeps the daemon stable. 0.3.0 cluster (memory:
+  `feedback_telepty_send_key_regression.md`) was a daemon-side change that
+  rippled into manual-override breakage. Client-side change has a strictly
+  smaller blast radius.
+
+## File map
+
+| File | Change | LoC delta |
+|---|---|---|
+| `cli.js` (inject command) | Parse `--submit-force` + `--submit-retry`. Wrap existing `useSubmit` block in idempotent retry loop on 504-with-safe-reason. | +~55, -~25 |
+| `test/cli.test.js` | Three new tests: --submit-force passes force=true; --submit-retry retries on safe-reason 504; --submit-retry does NOT retry on hard-fail 504. | +~120 |
+| `CHANGELOG.md` | 0.3.3 entry. | +~30 |
+| `package.json` | 0.3.2 → 0.3.3. | +1, -1 |
+| `test/enforce-report.test.js:280` | Update stale version assertion 0.2.0 → 0.3.3. | +1, -1 |
+| `README.md` | Mention new flags in inject summary. | +~6 |
+
+No new files outside `test/` and `docs/`. No daemon changes. No new
+dependencies. Total surface ≪ 200 LoC including tests.
+
+## Tests
+
+### Unit / integration (`test/cli.test.js`)
+
+1. **`--submit-force` passes `force: true` to /submit**
+   Spawn a session, intercept `/submit` (use existing harness method or
+   inspect bus event), invoke `telepty inject --submit --submit-force <id>
+   "x"`, assert daemon received `{ force: true }` in the request body.
+
+2. **`--submit-retry N` retries on safe-reason 504**
+   Mock the daemon to return 504 `{reason: 'gated_dispatch_unconsumed'}`
+   on the first call and 200 on the second. Assert the CLI made exactly
+   2 POST /submit calls and exited 0. Assert `[retry 1/N]` is present
+   in stdout.
+
+3. **`--submit-retry N` does NOT retry on hard-fail 504**
+   Mock the daemon to return 504 `{reason: 'session_dead'}`. Assert the
+   CLI made exactly 1 POST /submit call (no retry).
+
+### Regression — full suite
+
+`npm test` — 229 tests, all should pass after updating the stale
+`enforce-report.test.js:280` version assertion.
+
+## Future-proofing notes
+
+- If the daemon adds new 504 reasons, they are by default **NOT** retry-
+  safe (the safe set is an explicit allowlist). Adding a new safe reason
+  is a one-line `RETRY_SAFE_REASONS.add(...)` change in `cli.js`.
+- The flag pair composes: `--submit-force --submit-retry 0` (force-once),
+  `--submit-force --submit-retry 2` (force, with idempotent retry on the
+  rare 503 — though force never returns 504 today).
+- The 300 ms retry delay is a constant, not a flag, to keep the surface
+  small. Empirically chosen at the upper end of the architect's
+  100–300 ms window for the autocomplete-dropdown-close case.

package/host-spec.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const DEFAULT_PORT = 3848;
+
+function parseHostSpec(value, defaultPort = DEFAULT_PORT) {
+  if (value === undefined || value === null || value === '') {
+    return { host: '127.0.0.1', port: defaultPort };
+  }
+
+  let raw = String(value).trim();
+  if (!raw) {
+    return { host: '127.0.0.1', port: defaultPort };
+  }
+
+  raw = raw.replace(/^https?:\/\//i, '');
+  raw = raw.replace(/\/.*$/, '');
+
+  const ipv6Bracketed = raw.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (ipv6Bracketed) {
+    const port = ipv6Bracketed[2] ? Number(ipv6Bracketed[2]) : defaultPort;
+    return { host: ipv6Bracketed[1], port };
+  }
+
+  const colonCount = (raw.match(/:/g) || []).length;
+  if (colonCount > 1) {
+    return { host: raw, port: defaultPort };
+  }
+
+  const hostPort = raw.match(/^(.+):(\d+)$/);
+  if (hostPort) {
+    return { host: hostPort[1], port: Number(hostPort[2]) };
+  }
+
+  return { host: raw, port: defaultPort };
+}
+
+function formatHostForUrl(host) {
+  if (host && host.includes(':') && !host.startsWith('[')) {
+    return `[${host}]`;
+  }
+  return host;
+}
+
+function buildDaemonUrl(value, defaultPort = DEFAULT_PORT) {
+  const { host, port } = parseHostSpec(value, defaultPort);
+  return `http://${formatHostForUrl(host)}:${port}`;
+}
+
+function buildDaemonWsUrl(value, defaultPort = DEFAULT_PORT) {
+  const { host, port } = parseHostSpec(value, defaultPort);
+  return `ws://${formatHostForUrl(host)}:${port}`;
+}
+
+module.exports = {
+  DEFAULT_PORT,
+  parseHostSpec,
+  formatHostForUrl,
+  buildDaemonUrl,
+  buildDaemonWsUrl
+};

package/mcp-server/index.mjs

@@ -34,9 +34,30 @@ function getAuthToken() {
 }
 
 function getDaemonUrl() {
-  const port = process.env.TELEPTY_PORT || "3848";
-  const host = process.env.TELEPTY_HOST || "127.0.0.1";
-  return `http://${host}:${port}`;
+  // TELEPTY_HOST accepts: `host`, `host:port`, or `http://host:port`. Embedded
+  // port from TELEPTY_HOST is used unless TELEPTY_PORT is set explicitly.
+  const explicitPort = process.env.TELEPTY_PORT ? Number(process.env.TELEPTY_PORT) : null;
+  const raw = process.env.TELEPTY_HOST || "127.0.0.1";
+  let stripped = String(raw).trim().replace(/^https?:\/\//i, "").replace(/\/.*$/, "");
+  let host = stripped;
+  let embeddedPort = null;
+  const ipv6Bracketed = stripped.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (ipv6Bracketed) {
+    host = ipv6Bracketed[1];
+    if (ipv6Bracketed[2]) embeddedPort = Number(ipv6Bracketed[2]);
+  } else {
+    const colonCount = (stripped.match(/:/g) || []).length;
+    if (colonCount === 1) {
+      const m = stripped.match(/^(.+):(\d+)$/);
+      if (m) {
+        host = m[1];
+        embeddedPort = Number(m[2]);
+      }
+    }
+  }
+  const port = explicitPort != null ? explicitPort : (embeddedPort != null ? embeddedPort : 3848);
+  const hostForUrl = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `http://${hostForUrl}:${port}`;
 }
 
 async function daemonFetch(endpoint, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.98",
+  "version": "0.3.5",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -9,9 +9,10 @@
     "telepty-mcp": "mcp-server/index.mjs"
   },
   "scripts": {
-    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js",
-    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js",
-    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js"
+    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js",
+    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
   "keywords": [
     "pty",
@@ -48,7 +49,7 @@
     "node-pty": "^1.2.0-beta.11",
     "prompts": "^2.4.2",
     "update-notifier": "^5.1.0",
-    "uuid": "^13.0.0",
+    "uuid": "^9.0.0",
     "ws": "^8.19.0",
     "zod": "^3.24.0"
   }

package/scripts/regen-snippet-fixtures.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildOutput } = require('../src/init/print-snippet');
+
+const projectRoot = path.resolve(__dirname, '..');
+const fixtureDir = path.join(projectRoot, 'tests', 'snippet-protocol', 'v1');
+const targets = ['claude', 'agents', 'gemini', 'all'];
+const formats = [
+  { name: 'markdown', ext: 'md' },
+  { name: 'json', ext: 'json' }
+];
+
+function createCaptureStream() {
+  return {
+    value: '',
+    write(chunk) {
+      this.value += chunk;
+    }
+  };
+}
+
+fs.mkdirSync(fixtureDir, { recursive: true });
+
+for (const target of targets) {
+  for (const format of formats) {
+    const stdout = createCaptureStream();
+    const stderr = createCaptureStream();
+    const code = buildOutput(['--print-snippet', '--target', target, '--format', format.name], {
+      stdout,
+      stderr
+    });
+
+    if (code !== 0) {
+      throw new Error(`failed to generate ${target} ${format.name}: ${stderr.value}`);
+    }
+
+    const fixturePath = path.join(fixtureDir, `golden-${target}.${format.ext}`);
+    fs.writeFileSync(fixturePath, stdout.value, 'utf8');
+  }
+}

package/skill-installer.js

@@ -1,8 +1,10 @@
+// LEGACY: grandfathered by ADR 2026-05-05-telepty-devkit-boundary §6.2.1. New installer behavior MUST land in @dmsdc-ai/aigentry-devkit. Bugfixes only.
 'use strict';
 
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { execSync } = require('child_process');
 const prompts = require('prompts');
 
 const TARGET_CLIENTS = {
@@ -10,22 +12,44 @@ const TARGET_CLIENTS = {
     label: 'Claude Code',
     globalDir: () => path.join(os.homedir(), '.claude', 'skills'),
     projectDir: (cwd) => path.join(cwd, '.claude', 'skills'),
-    defaultScope: 'global'
+    defaultScope: 'global',
+    homeDir: () => path.join(os.homedir(), '.claude'),
+    binary: 'claude'
   },
   codex: {
     label: 'Codex',
     globalDir: () => path.join(os.homedir(), '.codex', 'skills'),
     projectDir: (cwd) => path.join(cwd, '.codex', 'skills'),
-    defaultScope: 'global'
+    defaultScope: 'global',
+    homeDir: () => path.join(os.homedir(), '.codex'),
+    binary: 'codex'
   },
   gemini: {
     label: 'Gemini',
     globalDir: () => path.join(os.homedir(), '.gemini', 'skills'),
     projectDir: (cwd) => path.join(cwd, '.gemini', 'skills'),
-    defaultScope: 'project'
+    defaultScope: 'project',
+    homeDir: () => path.join(os.homedir(), '.gemini'),
+    binary: 'gemini'
   }
 };
 
+function hasCliBinary(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore', shell: '/bin/sh' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectInstalledClients() {
+  return Object.keys(TARGET_CLIENTS).filter((key) => {
+    const client = TARGET_CLIENTS[key];
+    return fs.existsSync(client.homeDir()) || hasCliBinary(client.binary);
+  });
+}
+
 function resolveSkillsSourceRoot(packageRoot = __dirname) {
   return path.join(packageRoot, 'skills');
 }
@@ -163,13 +187,23 @@ async function runInteractiveSkillInstaller(options = {}) {
     console.log(`Installing packaged skill: ${packagedSkills[0].name}`);
   }
 
+  const installedClients = options.detectClients
+    ? options.detectClients()
+    : detectInstalledClients();
+  const installedSet = new Set(installedClients);
+  const detectedLabel = installedClients.length
+    ? `Detected: ${installedClients.join(', ')}`
+    : 'No AI CLI detected — manual selection required';
+  console.log(detectedLabel);
+
   const selectedClientsAnswer = await promptImpl({
     type: 'multiselect',
     name: 'clients',
-    message: 'Select target clients',
+    message: 'Select target clients (detected CLIs pre-selected)',
     choices: Object.entries(TARGET_CLIENTS).map(([key, value]) => ({
-      title: value.label,
-      value: key
+      title: `${value.label}${installedSet.has(key) ? ' ✓ detected' : ' (not detected)'}`,
+      value: key,
+      selected: installedSet.has(key)
     })),
     min: 1
   });
@@ -262,6 +296,8 @@ async function runInteractiveSkillInstaller(options = {}) {
 module.exports = {
   TARGET_CLIENTS,
   copySkillDirectory,
+  detectInstalledClients,
+  hasCliBinary,
   installSkillsWithPlan,
   listPackagedSkills,
   resolveTargetDirectory,

package/skills/telepty/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty
-description: Overview of telepty — PTY multiplexer for AI session orchestration. Use this when user asks "what is telepty" or needs a getting-started guide.
+description: Overview of telepty — PTY multiplexer for AI session orchestration. Use this when user asks "what is telepty" or needs a getting-started guide. 키워드: 텔레프티, 텔레프티 개요, 시작하기, telepty 소개, 사용법, 가이드
 ---
 
 # telepty — Overview

package/skills/telepty-allow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-allow
-description: Create telepty sessions by wrapping CLI processes. Covers the allow/enable/wrap command for session creation and PTY management.
+description: Create telepty sessions by wrapping CLI processes. Covers the allow/enable/wrap command for session creation and PTY management. 키워드: 세션 생성, 세션 래핑, CLI 래핑, allow, 세션 만들기, PTY
 ---
 
 # telepty-allow — Create and Manage Sessions

package/skills/telepty-attach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-attach
-description: Attach interactively to a telepty session to view output and send input in real-time.
+description: Attach interactively to a telepty session to view output and send input in real-time. 키워드: 세션 접속, 세션 연결, 세션 들어가기, 어태치, attach, 실시간 보기
 ---
 
 # telepty-attach — Interactive Session Attachment

package/skills/telepty-broadcast/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-broadcast
-description: Send messages to multiple telepty sessions at once. Covers broadcast (all sessions) and multicast (selected targets).
+description: Send messages to multiple telepty sessions at once. Covers broadcast (all sessions) and multicast (selected targets). 키워드: 전체 공지, 모든 세션에, 일괄 전송, 브로드캐스트, 멀티캐스트, 다중 주입
 ---
 
 # telepty-broadcast — Multi-Target Messaging

package/skills/telepty-daemon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-daemon
-description: Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance.
+description: Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance. 키워드: 데몬 시작, 데몬 재시작, 데몬 종료, TUI, 대시보드, 데몬 상태, daemon
 ---
 
 # telepty-daemon — Daemon Management

package/skills/telepty-inject/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-inject
-description: Send messages, commands, and keystrokes to telepty sessions. Covers inject, enter, send-key, and reply commands.
+description: Send messages, commands, and keystrokes to telepty sessions. Covers inject, enter, send-key, and reply commands. 키워드: 세션에 메시지, 메시지 보내기, 전달, 주입, inject, 응답, 답장, 키 입력
 ---
 
 # telepty-inject — Send Messages to Sessions
@@ -51,14 +51,34 @@ If you expect a reply, ALWAYS include `--from` so the target knows where to resp
 telepty inject <target> "your message" --from $(echo $TELEPTY_SESSION_ID)
 ```
 
-### Cross-host inject
+### Cross-host inject — `<id>@<host>` syntax
 
-When the same session ID exists on multiple hosts:
+To inject into a session running on a different machine, append `@<host>` to
+the session ID. `<host>` can be a hostname, LAN IP, or Tailnet name.
 
 ```bash
-telepty inject session_id@remote-host "message"
+# Hostname
+telepty inject session_id@worker-01 "message"
+
+# LAN IP (daemon must be reachable on port 3848)
+telepty inject orchestrator-claude@172.28.4.165 "PING from build server"
+
+# With return address (recommended for cross-host)
+telepty inject orchestrator-claude@192.168.1.10 "task done" \
+  --from "$TELEPTY_SESSION_ID"
 ```
 
+**Requirements**:
+- The remote daemon must be reachable on port `3848` from the calling host
+  (firewall / LAN routing / Tailscale).
+- No SSH or sshd is required on either side — the call hits the remote
+  daemon's HTTP API directly.
+- Use the same `<id>@<host>` syntax for `attach`, `read-screen`, `enter`,
+  and `multicast` targets.
+
+Use this when the same session ID exists on multiple hosts, or when the
+calling host has no local daemon discovery (no Tailnet, mixed LAN, etc.).
+
 ## enter — Send Enter keystroke only
 
 ```bash
@@ -83,6 +103,58 @@ telepty reply "<message>"
 
 Automatically targets the session that last injected into yours (uses stored `lastInjectFrom`).
 
+## Report Convention (REPORT to orchestrator)
+
+When a sub-session finishes a task or needs to escalate state, it reports to the
+**orchestrator** session using the `REPORT:` prefix.
+
+### Hard rule: NEVER hardcode the orchestrator session ID
+
+Session IDs are volatile runtime identifiers — they may change across hosts,
+restarts, or topology shifts. Resolve the orchestrator ID at runtime from
+`telepty list --json` instead.
+
+### Standard pattern (telepty 0.3.3+)
+
+```bash
+# 1. Resolve orchestrator session ID at runtime (filter out role-suffixed peers)
+ORCH_ID=$(telepty list --json | python3 -c "import json,sys; \
+  print(next(s['id'] for s in json.load(sys.stdin) \
+    if 'orchestrator' in s['id'] \
+    and not any(x in s['id'] for x in ('coder','reviewer','architect','runner','tester','analyst','builder'))))")
+
+# 2. Inject the REPORT (retry-safe submit; --ref keeps payload short)
+telepty inject --ref --submit --submit-retry 2 \
+  --from "$TELEPTY_SESSION_ID" "$ORCH_ID" \
+  "REPORT: <one-line summary> | evidence: <commit/test/etc> | next: <handoff>"
+```
+
+### Convention rules
+
+- **Prefix**: messages MUST start with `REPORT:` so the orchestrator's event
+  classifier can route them.
+- **Return address**: include `--from "$TELEPTY_SESSION_ID"` so the orchestrator
+  knows which sub-session reported.
+- **Retry**: pass `--submit-retry 2` (telepty 0.3.3+). The retry is idempotent
+  on safe gate-timeout 504s (`gated_dispatch_unconsumed`, `gate_timeout`,
+  `no_prompt_symbol_seen`); hard-fail reasons (`session_dead`, `error`,
+  `restarting`, `no_state`) are not retried.
+- **Long payloads**: store the full body in a file and use `--ref <file>` so the
+  inject prompt itself stays short.
+- **Self-report (idempotent)**: a session reporting on its own behalf may use
+  `--submit-force` to bypass the render gate. Do NOT use `--submit-force` for
+  general inject — it can clobber in-flight user input.
+
+### Anti-patterns (DO NOT)
+
+- `telepty inject orchestrator-claude "..."` — hardcoded session ID; breaks the
+  moment the orchestrator is renamed or runs under a different CLI (codex,
+  gemini).
+- Embedding `aigentry-orchestrator-claude` in spec templates, scripts, or
+  docs as a literal target.
+- Reporting without the `REPORT:` prefix — the orchestrator cannot distinguish
+  a status report from a peer-to-peer message.
+
 ## Common Errors
 
 | Error | Cause | Fix |

package/skills/telepty-list/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-list
-description: Discover telepty sessions, check status and health. Covers list, session info, and status commands.
+description: Discover telepty sessions, check status and health. Covers list, session info, and status commands. 키워드: 세션 목록, 활성 세션, 세션 조회, 세션 상태, 세션 확인, 리스트
 ---
 
 # telepty-list — Discover Sessions and Check Status

package/skills/telepty-listen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-listen
-description: Monitor telepty events and read session screen output. Covers listen (event bus) and read-screen commands.
+description: Monitor telepty events and read session screen output. Covers listen (event bus) and read-screen commands. 키워드: 이벤트 모니터, 화면 확인, 화면 읽기, 이벤트 스트림, listen, read-screen, 모니터링
 ---
 
 # telepty-listen — Event Monitoring and Screen Reading

package/skills/telepty-rename/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-rename
-description: Rename, delete, and clean up telepty sessions. Session lifecycle management.
+description: Rename, delete, and clean up telepty sessions. Session lifecycle management. 키워드: 세션 이름 변경, 세션 삭제, 세션 정리, 세션 청소, rename, 라이프사이클
 ---
 
 # telepty-rename — Session Lifecycle Management

package/skills/telepty-session/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-session
-description: Multi-session orchestration — start multiple sessions at once and arrange terminal layouts. Covers session start and layout commands.
+description: Multi-session orchestration — start multiple sessions at once and arrange terminal layouts. Covers session start and layout commands. 키워드: 멀티 세션 시작, 다중 세션, 세션 레이아웃, 세션 일괄 시작, 멀티 시작, layout
 ---
 
 # telepty-session — Multi-Session Orchestration