ftown-bridge 0.3.14 → 0.3.16

package/dist/session-registry.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+const REGISTRY_PATH = join(homedir(), '.ftown', 'session-registry.json');
+function loadRegistry() {
+    try {
+        if (!existsSync(REGISTRY_PATH)) {
+            return { byWorkspace: {}, byConversation: {} };
+        }
+        const parsed = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+        return {
+            byWorkspace: parsed.byWorkspace ?? {},
+            byConversation: parsed.byConversation ?? {},
+        };
+    }
+    catch {
+        return { byWorkspace: {}, byConversation: {} };
+    }
+}
+function saveRegistry(data) {
+    mkdirSync(join(homedir(), '.ftown'), { recursive: true, mode: 0o700 });
+    const tmp = `${REGISTRY_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, REGISTRY_PATH);
+}
+export function registerSessionWorkspace(sessionId, workingDir) {
+    if (!workingDir?.trim())
+        return;
+    const data = loadRegistry();
+    data.byWorkspace[resolve(workingDir.trim())] = sessionId;
+    saveRegistry(data);
+}
+export function registerSessionConversation(sessionId, conversationId) {
+    if (!conversationId)
+        return;
+    const data = loadRegistry();
+    data.byConversation[conversationId] = sessionId;
+    saveRegistry(data);
+}
+export function unregisterSession(sessionId) {
+    const data = loadRegistry();
+    for (const [path, id] of Object.entries(data.byWorkspace)) {
+        if (id === sessionId)
+            delete data.byWorkspace[path];
+    }
+    for (const [conv, id] of Object.entries(data.byConversation)) {
+        if (id === sessionId)
+            delete data.byConversation[conv];
+    }
+    saveRegistry(data);
+}
+export function resolveSessionIdFromHookPayload(payload) {
+    const ftownId = payload.ftown_session_id;
+    if (typeof ftownId === 'string' && ftownId)
+        return ftownId;
+    const data = loadRegistry();
+    const conversationId = payload.conversation_id;
+    if (typeof conversationId === 'string' && conversationId) {
+        const byConv = data.byConversation[conversationId];
+        if (byConv)
+            return byConv;
+    }
+    const roots = payload.workspace_roots;
+    if (Array.isArray(roots) && typeof roots[0] === 'string' && roots[0]) {
+        const byWs = data.byWorkspace[resolve(roots[0])];
+        if (byWs)
+            return byWs;
+    }
+    return undefined;
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/session-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.js","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"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"}

package/dist/terminal-manager.d.ts

@@ -7,6 +7,8 @@ export interface ScreenData {
 export interface GrepMatch {
     lineNumber: number;
     text: string;
+    before?: string[];
+    after?: string[];
 }
 export interface GrepResult {
     matches: GrepMatch[];
@@ -25,7 +27,7 @@ export declare class TerminalManager {
     getRawBuffer(sessionId: string): string;
     serialize(sessionId: string, scrollback?: number): string;
     getScreen(sessionId: string, offset?: number, limit?: number): ScreenData;
-    grep(sessionId: string, pattern: string, offset?: number, limit?: number): GrepResult;
+    grep(sessionId: string, pattern: string, offset?: number, limit?: number, contextLines?: number): GrepResult;
     replay(sessionId: string, rawLog: string): void;
     resize(sessionId: string, cols: number, rows: number): void;
     destroy(sessionId: string): void;

package/dist/terminal-manager.js

@@ -1,5 +1,6 @@
 import xtermHeadless from '@xterm/headless';
 import serializeAddon from '@xterm/addon-serialize';
+import { FTOWN_XTERM_THEME } from './xterm-theme.js';
 const { Terminal } = xtermHeadless;
 const { SerializeAddon } = serializeAddon;
 export class TerminalManager {
@@ -18,6 +19,7 @@ export class TerminalManager {
                 rows: 40,
                 scrollback: this.scrollback,
                 allowProposedApi: true,
+                theme: FTOWN_XTERM_THEME,
             });
             const serializer = new SerializeAddon();
             terminal.loadAddon(serializer);
@@ -67,7 +69,7 @@ export class TerminalManager {
         const lines = allLines.slice(offset, offset + limit);
         return { lines, totalLines, offset, limit };
     }
-    grep(sessionId, pattern, offset = 0, limit = 1000) {
+    grep(sessionId, pattern, offset = 0, limit = 1000, contextLines = 0) {
         const managed = this.terminals.get(sessionId);
         if (!managed) {
             return { matches: [], totalMatches: 0, offset, limit };
@@ -80,14 +82,21 @@ export class TerminalManager {
             return { matches: [], totalMatches: 0, offset, limit };
         }
         const totalLines = managed.terminal.buffer.active.length;
-        const matches = [];
+        const lineTexts = [];
         for (let i = 0; i < totalLines; i++) {
             const line = managed.terminal.buffer.active.getLine(i);
-            if (line) {
-                const text = line.translateToString(true);
-                if (regex.test(text)) {
-                    matches.push({ lineNumber: i + 1, text });
+            lineTexts.push(line ? line.translateToString(true) : '');
+        }
+        const matches = [];
+        const ctx = Math.max(0, Math.min(10, contextLines));
+        for (let i = 0; i < lineTexts.length; i++) {
+            if (regex.test(lineTexts[i])) {
+                const entry = { lineNumber: i + 1, text: lineTexts[i] };
+                if (ctx > 0) {
+                    entry.before = lineTexts.slice(Math.max(0, i - ctx), i);
+                    entry.after = lineTexts.slice(i + 1, Math.min(lineTexts.length, i + 1 + ctx));
                 }
+                matches.push(entry);
             }
         }
         const totalMatches = matches.length;

package/dist/terminal-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-manager.js","sourceRoot":"","sources":["../src/terminal-manager.ts"],"names":[],"mappings":"AAAA,OAAO,aAAgD,MAAM,iBAAiB,CAAC;AAC/E,OAAO,cAAc,MAAM,wBAAwB,CAAC;AACpD,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC;AACnC,MAAM,EAAE,cAAc,EAAE,GAAG,cAAc,CAAC;AA2B1C,MAAM,OAAO,eAAe;IACT,SAAS,GAAiC,IAAI,GAAG,EAAE,CAAC;IACpD,UAAU,CAAS;IACnB,IAAI,CAAS;IAE9B,YAAY,UAAU,GAAG,KAAK,EAAE,IAAI,GAAG,GAAG;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAEO,cAAc,CAAC,SAAiB;QACtC,IAAI,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC;gBAC5B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,EAAE;gBACR,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,gBAAgB,EAAE,IAAI;aACvB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,cAAc,EAAE,CAAC;YACxC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YAC/B,OAAO,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;YAClD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,SAAiB,EAAE,IAAY;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvC,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5B,CAAC;IAED,WAAW,CAAC,SAAiB;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC;QAC/B,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,CAAC,SAAiB;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,SAAS,CAAC;IAC3B,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,UAAmB;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACrD,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACvD,IAAI,IAAI,EAAE,CAAC;gBACT,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;QACrD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,SAAiB,EAAE,OAAe,EAAE,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACzD,CAAC;QAED,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACzD,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,MAAM,OAAO,GAAgB,EAAE,CAAC;QAEhC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACvD,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC1C,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrB,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC5C,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;QACpC,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;QAC/D,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,SAAiB,EAAE,MAAc;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,CAAC,SAAiB,EAAE,IAAY,EAAE,IAAY;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,OAAO,CAAC,SAAiB;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"terminal-manager.js","sourceRoot":"","sources":["../src/terminal-manager.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -34,6 +34,7 @@ export interface Command {
 export type CommandType = 'create_session' | 'stop_session' | 'list_sessions' | 'get_history' | 'retry_session' | 'send_message' | 'rename_session' | 'remove_session' | 'bridge_exec' | 'clear_terminal' | 'update_session_parent';
 export interface CreateSessionPayload {
     command: string;
+    prompt?: string;
     name?: string;
     workingDir?: string;
     bridgeId?: string;

package/dist/xterm-theme.d.ts

@@ -0,0 +1,30 @@
+/** Match ui/src/components/Terminal.tsx so serialize/replay preserves agent colors. */
+export declare const FTOWN_XTERM_THEME: {
+    readonly background: "#07070a";
+    readonly foreground: "#e8e8f0";
+    readonly cursor: "#00ff88";
+    readonly cursorAccent: "#07070a";
+    readonly selectionBackground: "rgba(0, 255, 136, 0.15)";
+    readonly black: "#0a0a0d";
+    readonly red: "#ff4466";
+    readonly green: "#00ff88";
+    readonly yellow: "#ffaa00";
+    readonly blue: "#44aaff";
+    readonly magenta: "#cc66ff";
+    readonly cyan: "#00ddff";
+    readonly white: "#c8c8d8";
+    readonly brightBlack: "#44444f";
+    readonly brightRed: "#ff6680";
+    readonly brightGreen: "#33ffaa";
+    readonly brightYellow: "#ffcc44";
+    readonly brightBlue: "#66bbff";
+    readonly brightMagenta: "#dd88ff";
+    readonly brightCyan: "#44eeff";
+    readonly brightWhite: "#e8e8f0";
+};
+/**
+ * Ink-based CLIs (Cursor Agent) emit no ANSI colors unless truecolor is advertised.
+ * The bridge process often inherits NO_COLOR=1 from Cursor IDE — strip it for PTY children
+ * unless the user explicitly opts out via session env (NO_COLOR=1 or FTOWN_NO_COLOR=1).
+ */
+export declare function applyTerminalColorEnv(env: Record<string, string>): void;

package/dist/xterm-theme.js

@@ -0,0 +1,38 @@
+/** Match ui/src/components/Terminal.tsx so serialize/replay preserves agent colors. */
+export const FTOWN_XTERM_THEME = {
+    background: '#07070a',
+    foreground: '#e8e8f0',
+    cursor: '#00ff88',
+    cursorAccent: '#07070a',
+    selectionBackground: 'rgba(0, 255, 136, 0.15)',
+    black: '#0a0a0d',
+    red: '#ff4466',
+    green: '#00ff88',
+    yellow: '#ffaa00',
+    blue: '#44aaff',
+    magenta: '#cc66ff',
+    cyan: '#00ddff',
+    white: '#c8c8d8',
+    brightBlack: '#44444f',
+    brightRed: '#ff6680',
+    brightGreen: '#33ffaa',
+    brightYellow: '#ffcc44',
+    brightBlue: '#66bbff',
+    brightMagenta: '#dd88ff',
+    brightCyan: '#44eeff',
+    brightWhite: '#e8e8f0',
+};
+/**
+ * Ink-based CLIs (Cursor Agent) emit no ANSI colors unless truecolor is advertised.
+ * The bridge process often inherits NO_COLOR=1 from Cursor IDE — strip it for PTY children
+ * unless the user explicitly opts out via session env (NO_COLOR=1 or FTOWN_NO_COLOR=1).
+ */
+export function applyTerminalColorEnv(env) {
+    env.TERM = env.TERM || 'xterm-256color';
+    if (env.FTOWN_NO_COLOR === '1' || env.NO_COLOR === '1' || env.NO_COLOR === 'true') {
+        return;
+    }
+    env.COLORTERM = 'truecolor';
+    env.FORCE_COLOR = '3';
+}
+//# sourceMappingURL=xterm-theme.js.map

package/dist/xterm-theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xterm-theme.js","sourceRoot":"","sources":["../src/xterm-theme.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,UAAU,EAAE,SAAS;IACrB,UAAU,EAAE,SAAS;IACrB,MAAM,EAAE,SAAS;IACjB,YAAY,EAAE,SAAS;IACvB,mBAAmB,EAAE,yBAAyB;IAC9C,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,WAAW,EAAE,SAAS;IACtB,SAAS,EAAE,SAAS;IACpB,WAAW,EAAE,SAAS;IACtB,YAAY,EAAE,SAAS;IACvB,UAAU,EAAE,SAAS;IACrB,aAAa,EAAE,SAAS;IACxB,UAAU,EAAE,SAAS;IACrB,WAAW,EAAE,SAAS;CACd,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA2B;IAC/D,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAExC,IAAI,GAAG,CAAC,cAAc,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAClF,OAAO;IACT,CAAC;IAED,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC;IAC5B,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC;AACxB,CAAC"}

package/hooks/notify.sh

@@ -1,16 +1,48 @@
 #!/bin/bash
 INPUT=$(cat)
-PORT="${FTOWN_HOOK_PORT}"
-SESSION_ID="${FTOWN_SESSION_ID}"
-TOKEN="${FTOWN_HOOK_TOKEN}"
+
+PORT="${FTOWN_HOOK_PORT:-}"
+SESSION_ID="${FTOWN_SESSION_ID:-}"
+TOKEN="${FTOWN_HOOK_TOKEN:-}"
+
+BRIDGE_JSON="${HOME}/.ftown/bridge.json"
+REGISTRY="${HOME}/.ftown/session-registry.json"
+
+if [ -z "$PORT" ] && [ -f "$BRIDGE_JSON" ]; then
+  PORT=$(jq -r '.port // empty' "$BRIDGE_JSON" 2>/dev/null)
+  if [ -z "$TOKEN" ]; then
+    TOKEN=$(jq -r '.token // empty' "$BRIDGE_JSON" 2>/dev/null)
+  fi
+fi
+
+if [ -z "$SESSION_ID" ] && [ -n "$INPUT" ]; then
+  CONV=$(echo "$INPUT" | jq -r '.conversation_id // empty' 2>/dev/null)
+  WS=$(echo "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+  if [ -f "$REGISTRY" ]; then
+    if [ -n "$CONV" ]; then
+      SESSION_ID=$(jq -r --arg c "$CONV" '.byConversation[$c] // empty' "$REGISTRY" 2>/dev/null)
+    fi
+    if [ -z "$SESSION_ID" ] && [ -n "$WS" ]; then
+      SESSION_ID=$(jq -r --arg w "$WS" '.byWorkspace[$w] // empty' "$REGISTRY" 2>/dev/null)
+    fi
+  fi
+fi
+
 if [ -z "$PORT" ] || [ -z "$SESSION_ID" ]; then
   exit 0
 fi
-PAYLOAD=$(echo "$INPUT" | jq -c --arg sid "$SESSION_ID" '. + {ftown_session_id: $sid}')
+
+PAYLOAD=$(echo "$INPUT" | jq -c --arg sid "$SESSION_ID" '. + {ftown_session_id: $sid}' 2>/dev/null)
+if [ -z "$PAYLOAD" ]; then
+  PAYLOAD=$(jq -nc --arg sid "$SESSION_ID" --arg ev "${HOOK_EVENT_NAME:-hook}" \
+    '{ftown_session_id: $sid, hook_event_name: $ev}')
+fi
+
 AUTH_ARGS=()
 if [ -n "$TOKEN" ]; then
   AUTH_ARGS+=(-H "Authorization: Bearer ${TOKEN}")
 fi
+
 curl -s -X POST "http://localhost:${PORT}/hook" \
   -H "Content-Type: application/json" \
   "${AUTH_ARGS[@]}" \

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "ftown-bridge",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "ftown-bridge": "dist/index.js"
+    "ftown-bridge": "dist/index.js",
+    "ftown-harness": "dist/harness-cli.js",
+    "ftown-sessions": "bin/ftown-sessions"
   },
   "files": [
     "dist",
-    "hooks"
+    "bin",
+    "hooks",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "start": "tsx src/index.ts",
-    "dev": "tsx watch src/index.ts"
+    "dev": "tsx watch src/index.ts",
+    "harness": "tsx src/harness-cli.ts"
   },
   "engines": {
     "node": ">=22"

package/skills/bridge-harness/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: bridge-harness
+description: Control local ftown-bridge sessions via auto-deployed ~/.ftown/bin/ftown-harness. Triggers on bridge harness, /bridge-harness, bridge sessions.
+---
+
+# bridge-harness
+
+## Entry (auto-deployed)
+
+```bash
+~/.ftown/bin/ftown-harness <cmd>
+```
+
+Read `~/.ftown/harness-agent.md` on each bridge start. Never curl/lsof the local bridge API.
+
+## Playbook
+
+```bash
+ftown-harness status
+ftown-harness here -n 25    # tails log even if process dead (status=error)
+ftown-harness ls --tail 3   # log=N on each row; previews dead sessions with logs
+ftown-harness grep ftown "error|FAIL" -C 2
+```
+
+## Commands
+
+| Cmd | Notes |
+|-----|-------|
+| `here -n N` | Workspace walk-up; **tails when dead** if log exists |
+| `ls --tail N` | Shows `log=lines`; preview any session with logs |
+| `tail` / `grep` | ANSI+OSC stripped; `grep -C 2` context |
+| `send` | `--dry-run` first; `-s` submit; only when user asks |
+| `--json` | `ftown-harness --json ls` etc. |
+
+Lookup: exact name → substring → id prefix.
+
+## Dead vs error
+
+`status=error` + `alive=false` does **not** mean no logs. Use `here`/`tail` — they read persisted terminal logs.
+
+## context-mode
+
+Use `ftown-harness` in Bash only. No curl/wget to 127.0.0.1.

package/skills/ftown-sessions/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ftown-sessions
+description: >-
+  Observe and control other ftown CLI agent sessions on the same machine. Use the
+  ftown-sessions CLI (~/.ftown/ftown-sessions) to list, create, read, and drive
+  sibling sessions while running inside a ftown-managed Claude Code or Cursor Agent
+  session.
+---
+
+# ftown cross-session CLI
+
+**Prefer the CLI** — installed to `~/.ftown/ftown-sessions` whenever `ftown-bridge` is running. It reads `~/.ftown/bridge.json` automatically.
+
+```bash
+~/.ftown/ftown-sessions --help
+```
+
+Skill copy (same binary via wrapper): `scripts/ftown-sessions` in this skill directory.
+
+**Trust model:** anyone who can read `bridge.json` can control **every** ftown session on that bridge.
+
+## Commands
+
+```bash
+# List sessions (JSON)
+~/.ftown/ftown-sessions list
+
+# Spawn a child agent (uses FTOWN_SESSION_ID for --parent)
+~/.ftown/ftown-sessions create \
+  --shell cursor \
+  --prompt "Review the auth module and summarize" \
+  --workdir /path/to/repo \
+  --name auth-review \
+  --parent
+
+# Metadata
+~/.ftown/ftown-sessions get <session-id>
+
+# Terminal output (plain lines; add --json for structured)
+~/.ftown/ftown-sessions screen <session-id> --limit 200
+
+# Search output
+~/.ftown/ftown-sessions grep <session-id> --pattern 'error|failed'
+
+# Type into another running session
+~/.ftown/ftown-sessions keys <session-id> 'y'
+
+# Liveness
+~/.ftown/ftown-sessions running <session-id>
+```
+
+### Create options
+
+| Flag | Description |
+|------|-------------|
+| `--shell` | `cursor`, `claude`, `shell`, `opencode`, … (default `claude`) |
+| `--prompt` | Initial message sent after spawn |
+| `--workdir` | Working directory |
+| `--name` | Dashboard label |
+| `--command` | Full command override (skips `--shell` builder) |
+| `--parent` | Set parent to `$FTOWN_SESSION_ID` |
+| `--parent-id` | Explicit parent session UUID |
+| `--model` | Cursor model name |
+
+Returns JSON with the new `session.id` — use that id for `screen` / `grep` / `keys`.
+
+## Typical workflow
+
+```bash
+CLI=~/.ftown/ftown-sessions
+
+$CLI list
+$CLI create --shell cursor --prompt "Run tests and report" --workdir "$PWD" --parent
+# -> note session.id from JSON
+
+$CLI screen <child-id> --limit 100
+$CLI grep <child-id> --pattern 'FAIL|Error'
+```
+
+## Environment
+
+Spawned ftown sessions receive:
+
+- `FTOWN_SESSION_ID` — this session (use with `--parent`)
+- `FTOWN_HOOK_PORT` / `FTOWN_HOOK_TOKEN` — hook forwarding (not for cross-session control)
+
+## HTTP API (optional)
+
+The CLI wraps the loopback API. Raw access if needed:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/sessions` | List |
+| POST | `/api/sessions` | Create |
+| GET | `/api/sessions/:id/screen` | Terminal lines |
+| POST | `/api/sessions/:id/grep` | Search |
+| POST | `/api/sessions/:id/keys` | Send keys |
+
+## If the CLI is missing
+
+Start or restart **ftown-bridge** on this machine. It installs `~/.ftown/ftown-sessions`, `~/.ftown/notify.sh`, and updates this skill under `~/.agents/skills/ftown-sessions/`.

package/skills/ftown-sessions/scripts/ftown-sessions

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Delegates to the bridge-installed CLI (~/.ftown/ftown-sessions).
+set -euo pipefail
+exec "${HOME}/.ftown/ftown-sessions" "$@"