Dev

.gitattributes

@@ -0,0 +1,41 @@
+# ── Force LF for Unix-format files regardless of host's core.autocrlf ──
+#
+# Why: a developer with `git config core.autocrlf=true` on Windows will
+# silently get CRLF on every text file at checkout, including shell
+# scripts.  Real-world hit on 2026-05-08: running scripts/restart-daemon.cmd
+# (which calls `npm install` / `npm run build` / `npm link --force`)
+# triggered git to refresh `bin/imcodes-launch.sh`, autocrlf converted it
+# to CRLF, `git status` showed it modified, and a careless `git add .`
+# would have committed CRLF into a #!/usr/bin/env bash script — bash on
+# Linux/macOS treats the trailing `\r` as part of the next token and
+# fails on every line ("$'\r': command not found", broken `if` tests,
+# malformed variable assignments, etc.).
+#
+# `text eol=lf` means: treat as text in the index, force LF on checkout
+# everywhere — overriding any local core.autocrlf=true setting.
+*.sh text eol=lf
+*.bash text eol=lf
+*.mjs text eol=lf
+*.cjs text eol=lf
+*.mts text eol=lf
+*.cts text eol=lf
+# Files that have a Unix shebang interpreter — bin entries in npm
+# packages and the husky hook scripts.  Their extensions vary or are
+# missing, so list them explicitly.
+bin/* text eol=lf
+.husky/_/husky.sh text eol=lf
+
+# ── Force CRLF on Windows-only batch / VBS files regardless of host ──
+#
+# Why: cmd.exe parses LF inconsistently (especially inside `if (...)` blocks)
+# and a `\r`-less line tail can swallow the next line as part of the previous
+# command. Without this rule, git on macOS/Linux checks the file out with LF
+# (matching the blob), and any test that reads the bytes directly trips a
+# "bare LF — needs CRLF" assertion (see test/util/restart-daemon-cmd.test.ts).
+#
+# `text eol=crlf` means: treat as text in the index, force CRLF on checkout
+# everywhere. The blob can still be LF — git converts on the way out.
+*.cmd text eol=crlf
+*.bat text eol=crlf
+*.vbs text eol=crlf
+*.ps1 text eol=crlf

.github/workflows/ci.yml

@@ -78,6 +78,18 @@ jobs:
       - run: npm run build
       - run: npm run test:unit
 
+  preview-dist-smoke:
+    name: Preview Dist Smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION_PRIMARY }}
+          cache: 'npm'
+      - run: ./scripts/ci-npm-ci.sh .
+      - run: npm run test:preview-dist
+
   embedding-real-tests:
     name: Embedding Integration Tests
     runs-on: ubuntu-latest
@@ -132,7 +144,11 @@ jobs:
       - run: bash ./scripts/ci-npm-ci.sh .
       - run: npm run build
       - name: Run Windows-specific unit tests
-        run: npx vitest run test/agent/wezterm.test.ts test/daemon/hook-send.test.ts test/daemon/env-injection.test.ts test/cli/send.test.ts test/util/windows-daemon.test.ts test/util/windows-upgrade-script.test.ts test/util/windows-launch-artifacts.test.ts test/util/windows-launch-artifacts.cmd-parse.test.ts test/util/windows-stale-watchdog-cleanup.test.ts test/util/postinstall-sharp-repair.test.ts
+        run: npx vitest run test/agent/wezterm.test.ts test/daemon/hook-send.test.ts test/daemon/env-injection.test.ts test/cli/send.test.ts test/util/windows-daemon.test.ts test/util/windows-upgrade-script.test.ts test/util/windows-upgrade-runner.test.ts test/util/windows-launch-artifacts.test.ts test/util/windows-launch-artifacts.cmd-parse.test.ts test/util/postinstall-sharp-repair.test.ts test/util/sharp-repair-script.test.ts test/util/restart-daemon-cmd.test.ts
+        env:
+          IMCODES_MUX: wezterm
+      - name: Run Windows process-cleanup regression tests
+        run: npx vitest run test/util/windows-stale-watchdog-cleanup.test.ts
         env:
           IMCODES_MUX: wezterm
 
@@ -148,7 +164,9 @@ jobs:
       - run: bash ./scripts/ci-npm-ci.sh .
       - run: npm run build
       - name: Run Windows ConPTY / startup regression tests
-        run: npx vitest run test/agent/conpty.test.ts test/agent/drivers/drivers.test.ts test/util/windows-daemon.test.ts test/util/windows-upgrade-script.test.ts test/util/windows-launch-artifacts.test.ts test/util/windows-launch-artifacts.cmd-parse.test.ts test/util/windows-stale-watchdog-cleanup.test.ts
+        run: npx vitest run test/agent/conpty.test.ts test/agent/drivers/drivers.test.ts test/util/windows-daemon.test.ts test/util/windows-upgrade-script.test.ts test/util/windows-upgrade-runner.test.ts test/util/windows-launch-artifacts.test.ts test/util/windows-launch-artifacts.cmd-parse.test.ts test/util/sharp-repair-script.test.ts test/util/restart-daemon-cmd.test.ts
+      - name: Run Windows ConPTY process-cleanup regression tests
+        run: npx vitest run test/util/windows-stale-watchdog-cleanup.test.ts
   # ── Web frontend tests ────────────────────────────────────────────────────
 
   web-tests-unit:
@@ -291,10 +309,17 @@ jobs:
         with:
           node-version: ${{ env.NODE_VERSION_PRIMARY }}
           cache: 'npm'
-      - name: Install tmux
-        run: sudo apt-get install -y tmux
-      - name: Prime tmux server
-        run: tmux new-session -d -s init && tmux kill-session -t init
+      # tmux is no longer needed here: `test:coverage` skips the e2e project
+      # (which spawns real tmux + agent processes), saving ~1 min per run.
+      #
+      # `npm run build` IS still needed: although most tests resolve from
+      # `src/` via vitest's tsx transform, two suites assert against the
+      # built output and FAIL without `dist/`:
+      #   - test/packaging.test.ts             (verifies bin/main/files paths)
+      #   - test/util/postinstall-sharp-repair.test.ts (executes dist/.../postinstall-sharp-repair.js)
+      # Both run in the `daemon` project, which is included in coverage. They
+      # pass in the regular Unit Tests jobs because those run `npm run build`
+      # first; coverage must do the same.
       - run: ./scripts/ci-npm-ci.sh .
       - name: Install web deps (needed for tsx component tests)
         run: ./scripts/ci-npm-ci.sh web

CLAUDE.md

@@ -88,7 +88,7 @@ The web project uses `i18next` with `react-i18next` for internationalization.
 - Main sessions and sub-sessions are the same session model. Treat them as equally important in behavior, queueing, timeline semantics, edit/undo, and lifecycle handling. Differences should come only from parent/attachment relationship and presentation constraints, not from weaker semantics for sub-sessions.
 - Agent types: Process = `'claude-code' | 'codex' | 'gemini' | 'opencode' | 'shell' | 'script'`, Transport = `'openclaw' | 'qwen'` — the `AgentType` union in `src/agent/detect.ts`.
 - **Pod-sticky routing (MANDATORY for daemon-dependent requests)**: The server runs multiple replicas. Each daemon connects to ONE pod via WebSocket. The ingress uses `:serverId` in the URL path to route requests to the pod holding that daemon's WS. Any endpoint that depends on the daemon (file transfer, session commands, Watch API) **MUST** include `:serverId` in the URL path (e.g., `/api/server/:serverId/...`). In-memory state (download tokens, WsBridge instances, terminal streams) is per-pod — requests without serverId routing will hit a random pod and fail.
-- **MANDATORY — Transport command liveness contract:** Daemon command receipt and urgent-control delivery MUST preserve current dev behavior. The daemon MUST NOT intercept `/compact`; `/compact` is an ordinary SDK-native message and is forwarded unchanged. Ordinary `session.send` ack is a daemon-receipt ack and MUST NOT wait for recall, live context bootstrap, memory lookup/enrichment, embedding, transport lock, pending relaunch, provider send-start, provider settlement, telemetry, or any background memory work. `/stop` and approval/feedback/control responses MUST use the priority path and MUST NOT be routed through or blocked by the ordinary send queue/locks.
+- **MANDATORY — Transport command liveness contract:** Daemon command receipt and urgent-control delivery MUST preserve current dev behavior. The daemon MUST NOT intercept `/compact`; `/compact` is an ordinary SDK-native message and is forwarded unchanged to the transport provider. Provider adapters that expose a native compact RPC (for example Codex app-server `thread/compact/start`) MUST translate the raw `/compact` command at the SDK boundary instead of sending it as model text. Ordinary `session.send` ack is a daemon-receipt ack and MUST NOT wait for recall, live context bootstrap, memory lookup/enrichment, embedding, transport lock, pending relaunch, provider send-start, provider settlement, telemetry, or any background memory work. `/stop` and approval/feedback/control responses MUST use the priority path and MUST NOT be routed through or blocked by the ordinary send queue/locks.
 - Server secrets (`JWT_SIGNING_KEY`) are set via environment variables, never committed.
 - E2E tests require tmux. They are auto-skipped when `SKIP_TMUX_TESTS=1` or inside a Claude Code session (`CLAUDECODE` env var set).
 - **MANDATORY — Test session hygiene:** Any e2e/integration test that creates tmux sessions, main sessions, sub-sessions, or temporary projects/cwds **MUST** use naming/path patterns covered by `shared/test-session-guard.ts`. If a new test introduces a new naming family, you **MUST** update `shared/test-session-guard.ts` and its tests in the same change. Leaked test sessions must never persist to `~/.imcodes/sessions.json`, must never be written to the server DB, and must be cleaned from live terminal backends on daemon startup.

bin/imcodes-launch.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# imcodes-launch — self-healing daemon supervisor.
+#
+# Entry point for systemd ExecStart / launchctl ProgramArguments. Sits
+# in front of the real Node entry and pre-flight-checks the global
+# install for half-finished upgrades:
+#
+#   - if `imcodes upgrade` (or any `npm install -g imcodes@…`) gets
+#     killed mid-write — power loss, OOM-kill, ssh-disconnect, etc —
+#     npm leaves CRITICAL_DEPS as empty placeholder directories
+#     (e.g. `node_modules/commander/` exists but has no package.json).
+#     The next daemon start hits ERR_MODULE_NOT_FOUND on the FIRST
+#     `import 'commander'`, exits 1, systemd Restart=always thrashes
+#     forever.
+#
+#   - this launcher detects that signature, re-installs the SAME
+#     pinned version (read from the surviving package.json — never
+#     rolls forward without explicit user intent), then execs the
+#     real daemon. systemd / launchctl never has to know.
+#
+# Pure bash by design — node_modules being broken is exactly when
+# Node-side guard rails go missing too. No tool we use here lives
+# under node_modules.
+#
+# Idempotent: if node_modules is healthy, this is just a thin wrapper
+# that exec's the real entry with no overhead beyond a directory stat.
+set -u
+
+# Resolve our own real path so we can find the package root regardless
+# of how npm symlinked the bin (`$PREFIX/bin/imcodes-launch ->
+# ../lib/node_modules/imcodes/bin/imcodes-launch.sh`). `readlink -f`
+# is GNU on Linux; on macOS we fall back to `python3 os.path.realpath`,
+# and finally `$0` raw if neither is around (works when invoked via
+# absolute path, which systemd always does).
+resolve_self() {
+  if command -v readlink >/dev/null 2>&1 && readlink -f "$0" >/dev/null 2>&1; then
+    readlink -f "$0"
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$0"
+  else
+    echo "$0"
+  fi
+}
+
+SELF_REAL="$(resolve_self)"
+PKG_ROOT="$(cd "$(dirname "$SELF_REAL")/.." 2>/dev/null && pwd)"
+ENTRY="$PKG_ROOT/dist/src/index.js"
+NODE="${IMCODES_NODE_BIN:-$(command -v node 2>/dev/null || echo /usr/bin/node)}"
+NPM="${IMCODES_NPM_BIN:-$(command -v npm 2>/dev/null || true)}"
+HOME_DIR="${IMCODES_HOME:-$HOME}"
+REPAIR_LOG="${IMCODES_LAUNCH_REPAIR_LOG:-$HOME_DIR/.imcodes/launch-repair.log}"
+
+log() {
+  echo "[imcodes-launch $(date '+%Y-%m-%d %H:%M:%S')] $*" >&2
+}
+
+# Critical deps — daemon CANNOT start without these. Each is a top-level
+# dependency directly required by `dist/src/index.js` or its synchronous
+# transitive imports. If npm install was killed mid-tarball-extract,
+# these dirs exist (npm pre-creates them before fetching) but have no
+# `package.json` inside.
+#
+# Keep this list short and stable — over-eager checks cost startup
+# latency on every healthy boot.
+CRITICAL_DEPS=(commander ws cors body-parser hono "@huggingface/transformers")
+
+# Returns 0 if a dep dir exists but lacks package.json (the half-install
+# signature); 1 otherwise. A missing dep dir entirely is also fine —
+# npm dedupes some packages to higher levels — only the EMPTY-DIR case
+# is the smoking gun.
+is_half_installed() {
+  local dep_dir="$1"
+  [ -d "$dep_dir" ] && [ ! -f "$dep_dir/package.json" ]
+}
+
+# Clear stale `upgrade.lock.d/` left behind by killed `imcodes upgrade`
+# runs. The lock isn't a daemon-blocker on Linux/macOS (it gates only
+# the next upgrade attempt — see step 0.5 of the bash upgrade script)
+# but a stuck lock surprises operators ("why does my upgrade say
+# 'another upgrade is in progress'?"). The bash upgrade script has a
+# 1800 s stale watchdog that fires when a NEW upgrade is initiated;
+# this is the same logic, but at daemon-start time, so the lock gets
+# cleared even if no human-or-cron-triggered upgrade ever arrives.
+#
+# Cheap: a stat per startup. Idempotent: never touches a lock that's
+# fresh (a real upgrade really does block daemon restarts during its
+# 5–60 s install window).
+LOCK_DIR="$HOME_DIR/.imcodes/upgrade.lock.d"
+LOCK_STALE_AFTER_SEC="${IMCODES_LAUNCH_LOCK_STALE_AFTER_SEC:-1800}"
+if [ -d "$LOCK_DIR" ]; then
+  started=""
+  source="none"
+  if [ -f "$LOCK_DIR/started" ]; then
+    started="$(cat "$LOCK_DIR/started" 2>/dev/null || true)"
+    source="started-file"
+  fi
+  # Fall back to dir mtime if `started` was never written. `stat -c %Y`
+  # is GNU; `stat -f %m` is BSD. Try both — empty (= "stat failed") is
+  # treated as "unknown age", NOT zero, so we don't accidentally
+  # classify a fresh lock as stale because of a probe error.
+  if [ -z "$started" ]; then
+    started="$(stat -c %Y "$LOCK_DIR" 2>/dev/null || stat -f %m "$LOCK_DIR" 2>/dev/null || true)"
+    source="dir-mtime"
+  fi
+  # Reject blanks / non-numerics — anything else means we couldn't
+  # determine the age and SHOULD NOT decide to delete.
+  case "$started" in
+    ''|*[!0-9]*) started="" ;;
+  esac
+  if [ -n "$started" ]; then
+    now="$(date +%s)"
+    age=$(( now - started ))
+    if [ "$age" -gt "$LOCK_STALE_AFTER_SEC" ]; then
+      log "clearing stale upgrade.lock.d (age ${age}s, source=${source}, threshold ${LOCK_STALE_AFTER_SEC}s)"
+      rm -rf "$LOCK_DIR" 2>/dev/null || true
+    fi
+  fi
+fi
+
+needs_repair=0
+missing_summary=""
+if [ -d "$PKG_ROOT/node_modules" ]; then
+  for dep in "${CRITICAL_DEPS[@]}"; do
+    d="$PKG_ROOT/node_modules/$dep"
+    if is_half_installed "$d"; then
+      needs_repair=1
+      missing_summary="$missing_summary $dep"
+    fi
+  done
+fi
+
+# `dist/src/index.js` itself missing → the package files were also
+# wiped (rare; tarball extraction is per-package atomic in npm v9+,
+# but a corrupted disk or an accidentally-rm'd dist/ can produce
+# this). Treat as needs_repair so the launcher doesn't just exec a
+# missing file and lose the diagnostic.
+if [ ! -f "$ENTRY" ]; then
+  needs_repair=1
+  missing_summary="$missing_summary dist/src/index.js"
+fi
+
+if [ "$needs_repair" = "1" ]; then
+  if [ -z "$NPM" ]; then
+    log "node_modules half-installed (missing:$missing_summary) but npm not on PATH — cannot self-repair"
+  elif [ ! -f "$PKG_ROOT/package.json" ]; then
+    log "node_modules half-installed but $PKG_ROOT/package.json missing — cannot read pinned version"
+  else
+    pinned="$("$NODE" -e "console.log(require('$PKG_ROOT/package.json').version)" 2>/dev/null || true)"
+    if [ -z "$pinned" ]; then
+      log "node_modules half-installed but pinned version unreadable — proceeding without repair"
+    else
+      log "node_modules half-installed (missing:$missing_summary) — reinstalling imcodes@$pinned"
+      mkdir -p "$(dirname "$REPAIR_LOG")"
+      # Clear the leftovers npm leaves when its rename step fails:
+      #   1. `.imcodes-XXXXX` — npm's atomic-rename tempdir from the
+      #      interrupted install.
+      #   2. `~/.imcodes/upgrade.lock.d/` — daemon's own coordination
+      #      lock from the killed `imcodes upgrade` flow.
+      # Both make the next `npm install` fail with ENOTEMPTY/EBUSY.
+      GLOBAL_LIB="$(dirname "$PKG_ROOT")"
+      {
+        echo "==== $(date '+%Y-%m-%d %H:%M:%S') self-repair start (target imcodes@$pinned) ===="
+        echo "GLOBAL_LIB=$GLOBAL_LIB"
+        echo "PKG_ROOT=$PKG_ROOT"
+        echo "missing:$missing_summary"
+      } >>"$REPAIR_LOG" 2>&1 || true
+      rm -rf "$GLOBAL_LIB"/.imcodes-* "$HOME_DIR/.imcodes/upgrade.lock.d" >>"$REPAIR_LOG" 2>&1 || true
+      if "$NPM" install -g --ignore-scripts --prefer-online "imcodes@$pinned" >>"$REPAIR_LOG" 2>&1; then
+        log "self-repair OK"
+      else
+        log "self-repair FAILED — see $REPAIR_LOG"
+        # Fall through and let exec fail; systemd will keep retrying
+        # and the next attempt may succeed (e.g. transient network).
+      fi
+    fi
+  fi
+fi
+
+# Hand off to the real daemon. `exec` replaces this shell so
+# systemd/launchctl tracks the node PID directly — no extra hop.
+exec "$NODE" "$ENTRY" "$@"

openspec/changes/daemon-file-preview-worker/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-07