@dmsdc-ai/aigentry-telepty 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [0.6.6] - 2026-06-14
+
+### Fixed — duplicate same-id `allow` flap loop + `kill` doesn't stick (#56)
+
+- **A second `telepty allow --id <X>` no longer makes the session undeliverable-to.** Previously a
+  duplicate wrap-owner caused the daemon to oscillate between owners (`Total: 1 ↔ 2`, repeated
+  "Replacing stale ownerWs"), so the session never stayed `ready for inject` and **injects were
+  silently dropped**. The daemon now does a **durable last-writer-wins Replace**: the displaced
+  owner is closed with a dedicated **`4001 'Owner replaced'`** code (reason-independent — a bare
+  terminate delivered an empty reason that the bridge mis-read as a reconnect), and the CLI treats
+  `4001` as a clean exit with **no reconnect**. The `1000 'Session destroyed'` path is untouched;
+  the `#536` owner-token guard still suppresses the displaced bridge's stale-token DELETE (no
+  shared-fate cascade). Total settles at 1.
+- **`telepty kill --force` now sticks.** The owning wrap-owner PID is captured at `?owner=1` claim
+  time (previously only set on reconnect-register, so a first-connect owner had a null pid and could
+  re-register after a kill). Combined with the durable Replace, a killed session no longer respawns.
+  Cross-platform (`taskkill /T /F` on Windows).
+
+### Added — daemon lifecycle: `daemon start` (detached) / `stop` / `restart` (#55)
+
+- **`telepty daemon` is no longer foreground-only.** Previously the `daemon` command ignored its
+  subcommand argument and always started a foreground daemon (so `daemon stop` actually *started*
+  one, and there was no `restart`). Now:
+  - **`telepty daemon start`** — starts the daemon **detached/background** and returns control to the
+    shell immediately (prints pid + listen URL). Fixes one-command install/automation flows.
+  - **`telepty daemon stop`** — terminates the daemon process (SIGTERM → SIGKILL) and frees the port.
+    **Surgical**: it targets only the state-file pid / configured-port owner and force-disables the
+    system-wide process scan, so it can **never reap an unrelated telepty daemon**.
+  - **`telepty daemon restart`** — stop + detached start (a cross-platform restart; replaces the
+    mac-only `launchctl kickstart` and gives Windows a restart it never had).
+  - Bare `telepty daemon` keeps its foreground behavior (install/launchd flows depend on it); the
+    internal version-mismatch auto-restart (`ensureDaemonRunning`) is unchanged. `telepty allow`
+    (session bridges) stays foreground by design.
+
 ## [0.6.5] - 2026-06-13
 
 ### Fixed — orchestrator REPORT loss: hold-and-redeliver queued injects until idle (#617)

package/cli.js

@@ -18,6 +18,7 @@ const {
   findPortOwnerPid,
   readDaemonState,
   readRestartFailureMarker,
+  stopDaemon,
   writeRestartFailureMarker
 } = require('./daemon-control');
 const { attachInteractiveTerminal, getTerminalSize, restoreTerminalModes } = require('./interactive-terminal');
@@ -428,6 +429,7 @@ function startDetachedDaemon() {
     stdio: 'ignore'
   });
   cp.unref();
+  return cp;
 }
 
 async function waitForDaemonHealth(maxMs = 5000) {
@@ -580,6 +582,15 @@ function isDaemonDestroyClose(code, reason) {
   return code === 1000 && reasonText === 'Session destroyed';
 }
 
+// telepty#56: a dedicated 4001 close means the daemon deterministically replaced this wrap-owner
+// with a newer ?owner=1 claim (durable last-writer-wins). The displaced bridge must EXIT, not
+// reconnect — reconnecting would re-contend for the id and oscillate (Total flaps 1<->2). The code
+// is the discriminator (not the reason): a half-open socket may never deliver the close reason.
+// Pure predicate, exposed for unit-testing.
+function isOwnerReplacedClose(code) {
+  return code === 4001;
+}
+
 function runUpdateInstall() {
   if (process.env.TELEPTY_SKIP_PACKAGE_UPDATE === '1') {
     return;
@@ -1231,6 +1242,58 @@ async function main() {
   }
 
   if (cmd === 'daemon') {
+    // telepty#55: real daemon-lifecycle surface. Pre-0.6.6 this block ignored
+    // args[1] entirely and ALWAYS started a foreground daemon — so `daemon start`
+    // blocked the shell, `daemon stop` actually STARTED a daemon, and `restart`
+    // didn't exist. We now parse the subcommand; bare `telepty daemon` keeps the
+    // foreground behavior for back-compat (install/launchd flows depend on it).
+    const sub = args[1];
+
+    if (sub === 'start') {
+      // Detached/background start: return control to the shell immediately
+      // (cross-platform spawn with detached + stdio:'ignore' + unref). The child
+      // IS the daemon process, so cp.pid is the daemon's pid.
+      const cp = startDetachedDaemon();
+      console.log(`\x1b[32m✅ Telepty daemon started (pid ${cp.pid}) → ${DAEMON_URL}\x1b[0m`);
+      return;
+    }
+
+    if (sub === 'stop') {
+      // Terminate the running daemon (state-file pid + configured-port owner),
+      // graceful SIGTERM→SIGKILL. Surgical: never a system-wide process sweep
+      // (that's `cleanup-daemons`). Internal auto-restart is untouched.
+      const results = stopDaemon({ port: Number(PORT) });
+      if (results.stopped.length === 0 && results.failed.length === 0) {
+        console.log('No telepty daemon running.');
+      } else {
+        if (results.stopped.length > 0) {
+          console.log(`\x1b[32m✅ Stopped telepty daemon (${results.stopped.map((d) => `pid ${d.pid}`).join(', ')}).\x1b[0m`);
+        }
+        if (results.failed.length > 0) {
+          console.error(`\x1b[31m❌ Failed to stop ${results.failed.length} daemon process(es): ${results.failed.map((d) => `pid ${d.pid}`).join(', ')}.\x1b[0m`);
+          process.exitCode = 1;
+        }
+      }
+      return;
+    }
+
+    if (sub === 'restart') {
+      // Clean cross-platform restart = surgical stop + detached start. Replaces
+      // the mac-only `launchctl kickstart` and gives Windows a restart it never
+      // had. Internal auto-restart (ensureDaemonRunning) is NOT touched.
+      stopDaemon({ port: Number(PORT) });
+      const cp = startDetachedDaemon();
+      console.log(`\x1b[32m✅ Telepty daemon restarted (pid ${cp.pid}) → ${DAEMON_URL}\x1b[0m`);
+      return;
+    }
+
+    if (sub) {
+      console.error('❌ Usage: telepty daemon [start|stop|restart]');
+      process.exit(1);
+    }
+
+    // Bare `telepty daemon` — FOREGROUND (back-compat: install/launchd flows run
+    // this and expect a blocking process). `daemon start` is the detached path.
     console.log('Starting telepty daemon...');
     // daemon.js binds the port only when launched as the daemon. The CLI reaches
     // it via require() (not as require.main), so signal intent explicitly — tests
@@ -1769,7 +1832,9 @@ async function main() {
     // Connect to daemon WebSocket with auto-reconnect
     // owner=1 tells daemon this is the allow bridge (owner), not an attach viewer.
     // Daemon uses this to reclaim ownership even if a stale ownerWs is still registered.
-    const wsUrl = `${daemonWsUrl(REMOTE_HOST)}/api/sessions/${encodeURIComponent(sessionId)}?token=${encodeURIComponent(getAuthToken())}&owner=1`;
+    // telepty#56: owner_pid lets the daemon record this bridge's PID at claim time so
+    // `kill --force` can SIGKILL the owning process (kill-stick), independent of register timing.
+    const wsUrl = `${daemonWsUrl(REMOTE_HOST)}/api/sessions/${encodeURIComponent(sessionId)}?token=${encodeURIComponent(getAuthToken())}&owner=1&owner_pid=${process.pid}`;
     let daemonWs = null;
     let wsReady = false;
     let reconnectAttempts = 0;
@@ -1889,6 +1954,16 @@ async function main() {
           }
           return;
         }
+        // #56: the daemon replaced this owner with a newer ?owner=1 claim (close 4001). Exit
+        // cleanly without reconnecting — reconnecting re-contends and oscillates. The teardown
+        // DELETE carries our now-stale ownerToken and is suppressed by the daemon's #536 guard,
+        // so the live new owner is not torn down (no shared-fate cascade).
+        if (isOwnerReplacedClose(code)) {
+          if (closeAllowSession()) {
+            exitAllowSession(0);
+          }
+          return;
+        }
         scheduleReconnect();
       });
 
@@ -3958,7 +4033,8 @@ Discuss the following topic from your project's perspective. Engage with other s
 \x1b[1mtelepty\x1b[0m — Connect any terminal to any terminal, any machine.
 
 \x1b[1mSession Management:\x1b[0m
-  telepty daemon                                 Start the background daemon (port 3848)
+  telepty daemon                                 Start the daemon in the foreground (port 3848)
+  telepty daemon start|stop|restart              Start (detached) / stop / restart the background daemon
   telepty spawn --id <id> <command> [args...]    Spawn a new background session
   telepty allow [--id <id>] [--idle-ttl 1h|off] [--auto-restart] <command> [args...]  Wrap a CLI for remote control
   telepty list [--json]                          List sessions (local + Tailnet)
@@ -4034,6 +4110,7 @@ if (require.main === module) {
 module.exports = {
   classifyBackend,        // #29: TERM_PROGRAM/CMUX/kitty → backend string
   isDaemonDestroyClose,   // #17 OQ-2: 1000 'Session destroyed' → terminate-not-reconnect
+  isOwnerReplacedClose,   // #56: 4001 'Owner replaced' → exit-not-reconnect (durable Replace)
   sanitizePathArg,        // #26: path-arg validation/normalization
   decideDaemonAction,     // #567: pure restart-decision policy (meta-primary; no I/O)
   ensureDaemonRunning,    // #567: orchestrator (injectable probes for unit-testing)

package/daemon-control.js

@@ -417,10 +417,32 @@ function cleanupDaemonProcesses(opts) {
   return { stopped, failed };
 }
 
+// telepty#55: user-facing `telepty daemon stop`. Unlike cleanupDaemonProcesses
+// (which ALSO sweeps the whole process table for ANY telepty daemon — the right
+// behavior for `cleanup-daemons` and internal repair), stop must be SURGICAL: it
+// targets only the daemon THIS CLI is configured for — the state-file pid and the
+// owner of the configured port (default 3848). It never blind-scans the process
+// table, so it can never reap an unrelated telepty daemon (e.g. another node's
+// daemon on a different port). This mirrors the #44/#15 survivor-detection surface
+// (state-file pid + port owner) and reuses cleanupDaemonProcesses' graceful
+// SIGTERM→SIGKILL kill path + stale-state cleanup with the global scan disabled.
+function stopDaemon(opts) {
+  const o = opts || {};
+  return cleanupDaemonProcesses({
+    ...o,
+    port: Number.isInteger(o.port) && o.port > 0 ? o.port : 3848,
+    // Force-disable the system-wide process scan unconditionally (never honor a
+    // caller-provided one) — this is the surgical guarantee: stop reaps only the
+    // state-file pid and the configured port's owner, never a table sweep.
+    listDaemonProcesses: () => []
+  });
+}
+
 module.exports = {
   DAEMON_STATE_FILE,
   claimDaemonState,
   cleanupDaemonProcesses,
+  stopDaemon,
   clearDaemonState,
   clearRestartFailureMarker,
   findParentProcessInfo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -37,9 +37,9 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "preuninstall": "node scripts/preuninstall.js",
-    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
-    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
+    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.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/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "typecheck": "tsc --noEmit",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },

package/skills/telepty/SKILL.md

@@ -10,8 +10,9 @@ telepty is a PTY multiplexer and session orchestrator. It creates, connects, and
 ## Quick Start
 
 ```bash
-# Start daemon
-telepty daemon
+# Start daemon in the background (detached; returns the shell immediately)
+telepty daemon start
+# (bare `telepty daemon` runs it in the FOREGROUND — used by install/launchd)
 
 # Create a session wrapping Claude Code
 telepty allow --id my-session claude
@@ -45,7 +46,7 @@ telepty tui
 
 - For humans: prefer natural-language examples and TUI, then raw CLI commands
 - For AI agents: use raw `telepty` commands directly for execution
-- When daemon is broken: repair first with `telepty cleanup-daemons && telepty daemon`
+- When daemon is broken: repair first with `telepty cleanup-daemons && telepty daemon start` (or `telepty daemon restart`)
 
 ## Related Skills
 

package/skills/telepty-allow/SKILL.md

@@ -57,6 +57,22 @@ COLUMNS=120 LINES=40 telepty allow --id headless-session claude
 | `TELEPTY_SESSION_ID` | The session ID you specified |
 | `TELEPTY_AVAILABLE` | `true` |
 
+### Duplicate `--id` is last-writer-wins (deterministic replace)
+
+Running `telepty allow --id <X> …` again for an id that already has a live wrap-owner
+**deterministically replaces** the old owner (last-writer-wins): the newer allow takes over the id,
+and the **older bridge exits** (close code `4001 'Owner replaced'` — it does not reconnect). The
+session stays continuously `ready for inject`; there is no owner flap and no dropped injects.
+
+This is the intended path for a clean restart (e.g. `orchestrator-boot.sh` kill-9s a stale bridge
+then re-`allow`s). You do not need to `kill` the old session first — the new `allow` reclaims it.
+
+### kill stops the owning process (kill sticks)
+
+`telepty kill <X> --force` terminates the **owning wrap-owner process**, not just the session
+record. The owner's PID is captured when the bridge claims the id, so `--force` SIGKILLs it
+(cross-platform: `taskkill /T /F` on Windows). A killed session does not silently re-register.
+
 ### Aliases
 
 `telepty enable` and `telepty wrap` are aliases for `telepty allow`.

package/skills/telepty-daemon/SKILL.md

@@ -1,20 +1,38 @@
 ---
 name: telepty-daemon
-description: 'Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance. 키워드: 데몬 시작, 데몬 재시작, 데몬 종료, TUI, 대시보드, 데몬 상태, daemon'
+description: 'Manage the telepty daemon — start (detached), stop, restart, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance. 키워드: 데몬 시작, 데몬 재시작, 데몬 종료, 백그라운드, TUI, 대시보드, 데몬 상태, daemon'
 ---
 
 # telepty-daemon — Daemon Management
 
-## daemon — Start the daemon
+## daemon — Start the daemon (foreground)
 
 ```bash
 telepty daemon
 ```
 
-Starts the telepty daemon on port 3848. The daemon manages all sessions, handles inject delivery, and serves the HTTP/WS API.
+Starts the telepty daemon on port 3848 **in the foreground** (blocks the shell). The daemon manages all sessions, handles inject delivery, and serves the HTTP/WS API. This is the form install/launchd flows use; for interactive/automation use, prefer `telepty daemon start` below.
 
 The daemon auto-starts when needed (e.g., `telepty allow` starts it automatically). Manual start is rarely needed.
 
+## daemon start | stop | restart — Background lifecycle
+
+```bash
+telepty daemon start      # start DETACHED in the background, return the shell immediately
+telepty daemon stop       # gracefully stop the running daemon (SIGTERM → SIGKILL), free the port
+telepty daemon restart    # stop, then start detached (clean cross-platform restart)
+```
+
+Cross-platform (macOS / Linux / Windows):
+
+- **`start`** spawns the daemon detached (`stdio` ignored, unref'd) and returns control to the shell at once, printing the pid and listen URL. Use this for one-command install/automation instead of the blocking foreground `telepty daemon`.
+- **`stop`** is surgical — it terminates only the daemon this CLI is configured for (the state-file pid and/or the owner of the configured port, default 3848). It does **not** sweep the whole process table (that is `cleanup-daemons`), so it never reaps an unrelated telepty daemon.
+- **`restart`** = `stop` then detached `start`. Replaces the macOS-only `launchctl kickstart` and gives Windows a restart it never had.
+
+Natural-language: "데몬 백그라운드로 시작", "데몬 종료해줘", "데몬 재시작", "start the daemon in the background", "stop/restart the daemon".
+
+> Internal auto-restart (version-mismatch recovery) is unaffected — these are user-facing controls layered on top.
+
 ## cleanup-daemons — Kill stale daemon processes
 
 ```bash

package/src/transport/websocket.js

@@ -103,11 +103,31 @@ function installWebSocketTransport(deps) {
     if (activeSession.type === 'wrapped' && (!activeSession.ownerWs || isOwnerConnect)) {
       const hadDisconnectedOwner = !isOpenWebSocket(activeSession.ownerWs) && activeSession.lastDisconnectedAt;
       if (isOwnerConnect && activeSession.ownerWs && activeSession.ownerWs !== ws) {
-        // Terminate the stale owner connection before claiming ownership
+        // telepty#56 (durable last-writer-wins Replace): close the displaced owner with the
+        // dedicated terminal code 4001 'Owner replaced' instead of a bare terminate(). A
+        // terminate() is an abnormal 1006 close, which a bridge reads as a transient drop and
+        // RECONNECTS — re-contending for the id and oscillating forever (Total flaps 1<->2,
+        // injects dropped). 4001 is reason-independent (WS 4000-4999 = app-reserved), so the
+        // displaced bridge exits without reconnecting even when the close reason is lost on a
+        // half-open TCP socket. The session RECORD survives under the new owner; no shared-fate
+        // cascade — the displaced bridge's now-stale ownerToken is suppressed by the #536 DELETE
+        // guard. A fallback terminate() reaps a half-open socket that never ACKs the close.
         console.log(`[WS] Replacing stale ownerWs for session ${sessionId}`);
-        activeSession.ownerWs.terminate();
+        const displaced = activeSession.ownerWs;
+        try { displaced.close(4001, 'Owner replaced'); } catch {}
+        setTimeout(() => {
+          if (displaced.readyState !== 3) { try { displaced.terminate(); } catch {} }
+        }, 1000);
       }
       activeSession.ownerWs = ws;
+      // telepty#56 (kill-stick): capture the owner PID at claim time. The reconnect-register POST
+      // only carries owner_pid on reconnect, so a first-connect owner would otherwise have a null
+      // ownerPid and `kill --force` could not SIGKILL the owning process. The bridge passes its pid
+      // on the ?owner=1 URL; record it so the kill path always has a process to signal.
+      const claimOwnerPid = Number(url.searchParams.get('owner_pid'));
+      if (Number.isInteger(claimOwnerPid) && claimOwnerPid > 0) {
+        activeSession.ownerPid = claimOwnerPid;
+      }
       // BUG-C: mint a fresh per-owner token on every claim/reclaim and push it to this owner.
       // The token is the exact "are-you-the-current-owner" discriminator the DELETE guard uses
       // to suppress a stale/displaced owner's teardown (shared-fate fix). Reclaim refreshes it,