pi-harness-runtime 1.1.50 → 1.1.77

package/harness/ssh-detach-interceptor.test.ts

@@ -0,0 +1,263 @@
+/**
+ * SSH Detach Interceptor — Tests
+ *
+ * Key insight on quoting:
+ * - `ssh user@host 'cmd &'` — & is INSIDE quotes → safe, SSH completes normally
+ * - `ssh user@host "cmd" &` — & is OUTSIDE quotes → risky, backgrounds SSH itself
+ * - `ssh user@host 'kill ... &' "2>/dev/null"` — & inside quotes, redirect outside → risky
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import {
+	isSshCommand,
+	isDetachedPattern,
+	hasBareAmpersand,
+	transformToDetached,
+	detectSsh,
+	isForegroundDaemonSsh,
+	addSshTimeoutGuard,
+	getDefaultSshTimeoutSeconds,
+} from "./ssh-detach-interceptor.js";
+
+describe("isSshCommand", () => {
+	const cases: Array<[string, boolean]> = [
+		["ssh user@host ls", true],
+		["ssh -o StrictHostKeyChecking=no user@host ls", true],
+		["echo 'pass' | ssh user@host ls", true],
+		["curl https://example.com", false],
+		["cd /home && ls", false],
+		["ssh user@host 'echo test &'", true],
+		["docker exec container ls", false],
+	];
+	cases.forEach(([cmd, expected]) => {
+		it(`${cmd.slice(0, 50)} → ${expected}`, () => {
+			assert.strictEqual(isSshCommand(cmd), expected);
+		});
+	});
+});
+
+describe("isDetachedPattern", () => {
+	const cases: Array<[string, boolean]> = [
+		// & is inside quotes → not detached (no nohup locally visible)
+		["ssh user@host 'cmd > /tmp/log 2>&1 & echo DONE'", false],
+		// bare & inside quotes → not detached
+		["ssh user@host 'cmd &'", false],
+		// nohup + redirect + echo DONE → detached
+		["ssh user@host 'nohup cmd > /tmp/log 2>&1 & echo DONE'", true],
+		// missing echo DONE → not detached
+		["ssh user@host 'cmd > /tmp/log &'", false],
+		// missing redirect → not detached
+		["ssh user@host 'nohup cmd &'", false],
+		// non-SSH → not detached
+		["curl https://example.com", false],
+	];
+	cases.forEach(([cmd, expected]) => {
+		it(`${cmd.slice(0, 55)} → ${expected}`, () => {
+			assert.strictEqual(isDetachedPattern(cmd), expected);
+		});
+	});
+});
+
+describe("hasBareAmpersand", () => {
+	// & outside quotes = risky (backgrounds SSH itself)
+	const risky: Array<[string, boolean]> = [
+		["ssh user@host 'cmd' &", true],
+		["ssh user@host 'kill 123' &", true],
+		["echo 'pass' | ssh user@host 'kill 123' &", true],
+		["ssh user@host 'cmd > /tmp/log 2>&1' &", true],
+	];
+	// & inside quotes = safe (SSH completes, remote side backgrounds)
+	const safe: Array<[string, boolean]> = [
+		["ssh user@host 'cmd &'", false],
+		["ssh user@host 'kill -9 123 && uvicorn &'", false],
+		["ssh user@host 'nohup cmd &'", false],
+		["ssh user@host 'cmd'", false],
+		["curl https://example.com", false],
+	];
+	[...risky, ...safe].forEach(([cmd, expected]) => {
+		it(`${cmd.slice(0, 50)} → ${expected}`, () => {
+			assert.strictEqual(hasBareAmpersand(cmd), expected);
+		});
+	});
+});
+
+describe("transformToDetached", () => {
+	it("leaves non-SSH commands unchanged", () => {
+		const cmd = "curl https://example.com";
+		assert.strictEqual(transformToDetached(cmd), cmd);
+	});
+
+	it("leaves already-detached SSH commands unchanged", () => {
+		const cmd = "ssh user@host 'cmd > /tmp/log 2>&1 & echo DONE'";
+		assert.strictEqual(transformToDetached(cmd), cmd);
+	});
+
+	it("transforms bare ssh 'cmd' & (risky: & outside quotes)", () => {
+		const cmd = "ssh user@host 'kill -9 123; sleep 2; uvicorn' &";
+		const result = transformToDetached(cmd);
+		assert.notStrictEqual(result, cmd);
+		assert.ok(result.includes("nohup"), "should add nohup");
+		assert.ok(result.includes("/tmp/herdr-ssh.log"), "should add log redirect");
+		assert.ok(result.includes("2>&1"), "should add stderr redirect");
+		assert.ok(result.includes("echo 'SSH_DETACHED'"), "should add DONE echo");
+	});
+
+	it("transforms pipelined ssh with bare & (risky: & outside quotes)", () => {
+		const cmd = "echo 'pass' | ssh user@host 'kill -9 123' &";
+		const result = transformToDetached(cmd);
+		assert.notStrictEqual(result, cmd);
+		assert.ok(result.includes("nohup"));
+		assert.ok(result.includes("echo 'SSH_DETACHED'"));
+	});
+
+	it("leaves & inside quotes unchanged (safe: SSH completes)", () => {
+		const cmd = "ssh user@host 'kill -9 123; uvicorn &'";
+		const result = transformToDetached(cmd);
+		assert.strictEqual(result, cmd); // no transform needed
+	});
+
+	it("uses custom log file", () => {
+		const cmd = "ssh user@host 'cmd' &";
+		const result = transformToDetached(cmd, { logFile: "/var/log/my-ssh.log" });
+		assert.ok(result.includes("/var/log/my-ssh.log"));
+	});
+});
+
+describe("detectSsh", () => {
+	it("warns on SSH with bare & outside quotes", () => {
+		const result = detectSsh("ssh user@host 'cmd' &");
+		assert.strictEqual(result.isSsh, true);
+		assert.strictEqual(result.hasBareAmpersand, true);
+		assert.strictEqual(result.isDetached, false);
+		assert.ok(result.suggestion.includes("nohup"));
+	});
+
+	it("no warning for & inside quotes (SSH completes normally)", () => {
+		const result = detectSsh("ssh user@host 'kill 123 && uvicorn &'");
+		assert.strictEqual(result.isSsh, true);
+		assert.strictEqual(result.isDetached, false);
+		assert.strictEqual(result.hasBareAmpersand, false);
+		assert.strictEqual(result.suggestion, "");
+	});
+
+	it("no detection for non-SSH", () => {
+		const result = detectSsh("curl https://example.com");
+		assert.strictEqual(result.isSsh, false);
+		assert.strictEqual(result.suggestion, "");
+	});
+});
+
+describe("isForegroundDaemonSsh", () => {
+	// The exact command that caused the 1911.9s hang (2026-09-14)
+	const HANG_CMD =
+		"echo 'manlucha' | ssh -tt frappe@100.101.238.114 \"cd /home/frappe/amos-saas/backend/services/worker && AMOS_API_URL=https://api.ezsysbot.com AMOS_WORKER_API_KEY=test /home/frappe/amos-saas/backend/.venv/bin/python -m amos_worker --video 2>&1 | head -10\"";
+
+	const risky: Array<[string, string]> = [
+		[
+			HANG_CMD,
+			"foreground ssh -tt running amos_worker poller (real 1911.9s hang)",
+		],
+		[
+			'ssh host "uvicorn main:app --host 0.0.0.0 --port 8100"',
+			"foreground uvicorn",
+		],
+		["ssh host 'python -m celery worker'", "celery worker"],
+		['ssh host "tail -f /var/log/app.log"', "tail -f"],
+		['ssh host "npm run dev"', "npm run dev"],
+		[
+			'ssh host "python -m my_package.daemon --poll"',
+			"python -m with daemon in module path",
+		],
+	];
+	risky.forEach(([cmd, label]) => {
+		it(`RISKY: ${label}`, () => {
+			assert.strictEqual(isForegroundDaemonSsh(cmd), true, cmd.slice(0, 80));
+		});
+	});
+
+	const safe: Array<[string, string]> = [
+		["ssh host 'ls -la'", "plain remote command"],
+		[
+			"timeout 60s ssh -o BatchMode=yes host 'uvicorn main:app'",
+			"local timeout guard",
+		],
+		[
+			"ssh host 'timeout 30 python -m amos_worker --video'",
+			"remote timeout guard",
+		],
+		[
+			"ssh host 'nohup python -m amos_worker --video > /tmp/w.log 2>&1 & echo DONE'",
+			"nohup detached",
+		],
+		["ssh -f host 'uvicorn main:app'", "ssh -f backgrounds itself"],
+		[
+			"python -m amos_worker --video",
+			"local (non-ssh) daemon command — not our scope",
+		],
+		["curl https://example.com", "not ssh"],
+	];
+	safe.forEach(([cmd, label]) => {
+		it(`SAFE: ${label}`, () => {
+			assert.strictEqual(isForegroundDaemonSsh(cmd), false, cmd.slice(0, 80));
+		});
+	});
+});
+
+describe("addSshTimeoutGuard", () => {
+	it("prefixes the ssh segment with timeout, preserving pipeline prefix", () => {
+		const cmd = "echo 'x' | ssh -tt host \"python -m amos_worker --video\"";
+		assert.strictEqual(
+			addSshTimeoutGuard(cmd, 300),
+			"echo 'x' | timeout 300s ssh -tt host \"python -m amos_worker --video\"",
+		);
+	});
+
+	it("uses default seconds when omitted", () => {
+		const cmd = "ssh host 'uvicorn main:app'";
+		assert.ok(addSshTimeoutGuard(cmd).startsWith("timeout "));
+		assert.ok(addSshTimeoutGuard(cmd).includes("s ssh host"));
+	});
+
+	it("invalid seconds returns command unchanged", () => {
+		const cmd = "ssh host 'uvicorn main:app'";
+		assert.strictEqual(addSshTimeoutGuard(cmd, 0), cmd);
+		assert.strictEqual(addSshTimeoutGuard(cmd, NaN), cmd);
+	});
+
+	it("non-ssh command returns unchanged", () => {
+		assert.strictEqual(addSshTimeoutGuard("ls -la"), "ls -la");
+	});
+});
+
+describe("getDefaultSshTimeoutSeconds", () => {
+	it("defaults to 300", () => {
+		delete process.env.PI_HARNESS_SSH_TIMEOUT_S;
+		assert.strictEqual(getDefaultSshTimeoutSeconds(), 300);
+	});
+
+	it("honours PI_HARNESS_SSH_TIMEOUT_S", () => {
+		const prev = process.env.PI_HARNESS_SSH_TIMEOUT_S;
+		try {
+			process.env.PI_HARNESS_SSH_TIMEOUT_S = "120";
+			assert.strictEqual(getDefaultSshTimeoutSeconds(), 120);
+			process.env.PI_HARNESS_SSH_TIMEOUT_S = "bogus";
+			assert.strictEqual(getDefaultSshTimeoutSeconds(), 300);
+		} finally {
+			if (prev === undefined) delete process.env.PI_HARNESS_SSH_TIMEOUT_S;
+			else process.env.PI_HARNESS_SSH_TIMEOUT_S = prev;
+		}
+	});
+});
+
+describe("detectSsh (timeout guard)", () => {
+	it("flags foreground daemon ssh with timeout suggestion", () => {
+		const result = detectSsh("ssh -tt host 'python -m amos_worker --video'");
+		assert.strictEqual(result.needsTimeoutGuard, true);
+		assert.ok(result.suggestion.includes("timeout"));
+	});
+
+	it("no timeout flag for plain ssh", () => {
+		const result = detectSsh("ssh host 'ls -la'");
+		assert.strictEqual(result.needsTimeoutGuard, false);
+	});
+});

package/harness/ssh-detach-interceptor.ts

@@ -0,0 +1,438 @@
+/**
+ * SSH Detach Interceptor
+ *
+ * Automatically transforms bare `ssh ... &` commands into detached patterns
+ * that don't hang the SSH session.
+ *
+ * Problem: `ssh user@host "command &"` keeps SSH open waiting for the background
+ * process. This causes 2000+ second hangs.
+ *
+ * Solution: Auto-inject nohup + redirect + DONE echo so SSH exits immediately
+ * while the process continues running on the server.
+ */
+
+/**
+ * Find the last SSH command in a string (handles pipelined commands).
+ * Returns { start, end } of the ssh ... part, or null if no SSH found.
+ */
+function findLastSshCommand(s: string): { start: number; end: number } | null {
+	// Find the LAST occurrence of "ssh " (word boundary)
+	const matches = [...s.matchAll(/\bssh\s+/gm)];
+	if (matches.length === 0) return null;
+
+	const lastMatch = matches[matches.length - 1];
+	const sshStart = lastMatch.index!;
+
+	// Find where the SSH command ends:
+	// Look for a | that's OUTSIDE quotes, which starts a new pipe segment
+	let sshEnd = s.length;
+	let depth = 0;
+	for (let i = sshStart; i < s.length; i++) {
+		const ch = s[i];
+		if (ch === "\\" && i + 1 < s.length) {
+			i++; // skip escaped char
+			continue;
+		}
+		if (depth > 0) {
+			if ((ch === '"' && depth === 1) || (ch === "'" && depth === 2)) {
+				depth = 0;
+			}
+		} else if (ch === '"') depth = 1;
+		else if (ch === "'") depth = 2;
+		else if (ch === "|") {
+			sshEnd = i;
+			break;
+		}
+	}
+	return { start: sshStart, end: sshEnd };
+}
+
+/**
+ * Check if a command is an SSH command.
+ */
+export function isSshCommand(command: string): boolean {
+	return /\bssh\s+/m.test(command.trim());
+}
+
+/**
+ * Check if an SSH command uses the detached pattern:
+ * nohup + redirect + trailing DONE echo. The chain may live remotely
+ * (inside the quoted command) or locally — either way ssh exits promptly.
+ *
+ * Note: a quoted `cmd &` alone (no redirect/echo) does NOT count.
+ */
+export function isDetachedPattern(command: string): boolean {
+	const sshRange = findLastSshCommand(command);
+	if (!sshRange) return false;
+	const sshPart = command.slice(sshRange.start, sshRange.end);
+	return (
+		/nohup\b/.test(sshPart) &&
+		(/>\s*\//.test(sshPart) || /2>&1/.test(sshPart)) &&
+		/echo\s+['"]?\w+['"]?\s*$/.test(command.trim())
+	);
+}
+
+/**
+ * Check if an SSH command has a trailing bare & OUTSIDE the quoted remote command.
+ * This is the risky pattern that backgrounds the SSH connection itself.
+ *
+ * NOT risky (safe): & inside the quoted remote command string
+ * RISKY (needs transform): & outside the quoted remote command (backgrounds SSH)
+ */
+export function hasBareAmpersand(command: string): boolean {
+	if (!isSshCommand(command)) return false;
+	if (isDetachedPattern(command)) return false;
+
+	const sshRange = findLastSshCommand(command);
+	if (!sshRange) return false;
+	const sshPart = command.slice(sshRange.start, sshRange.end);
+
+	// Extract the ssh prefix (ssh + host + flags) and the remote command argument
+	// The remote command is typically quoted; we need to find where it ends
+	// Strategy: find the last quoted string in the ssh part
+	let remoteCmdEnd = sshPart.length;
+
+	// Scan for the last closing quote outside escaped chars
+	for (let i = sshPart.length - 1; i >= 0; i--) {
+		if (sshPart[i] === "\\" && i > 0) {
+			i--; // skip escaped char
+			continue;
+		}
+		// Count if we see a quote — the first unescaped quote pair we encounter
+		// marks the end of the quoted remote command
+		if (sshPart[i] === '"' || sshPart[i] === "'") {
+			// Find the matching opening quote going forward
+			const closeQuote = sshPart[i];
+			let found = false;
+			for (let j = i - 1; j >= 0; j--) {
+				if (sshPart[j] === "\\") {
+					j--;
+					continue;
+				}
+				if (sshPart[j] === closeQuote) {
+					found = true;
+					break;
+				}
+			}
+			if (found) {
+				remoteCmdEnd = i + 1;
+				break;
+			}
+		}
+	}
+
+	// Everything after the quoted remote command
+	const afterQuotes = sshPart.slice(remoteCmdEnd).trim();
+	// Check if there's a bare & (not &&, not |&) outside the quoted part
+	return /^\s*&\s*$/.test(afterQuotes);
+}
+
+/**
+ * Check if an SSH command has a `&& ... &` or `; ... &` pattern INSIDE
+ * the quoted remote command. This means: "run A, then run B, then background B".
+ *
+ * This is risky because SSH waits for the WHOLE quoted command chain to complete.
+ * If B hangs (import error, DB timeout, port conflict), SSH never exits.
+ *
+ * RISKY: ssh ... "cd X && python uvicorn ... &"
+ * RISKY: ssh ... "cmd1; cmd2 &".
+ * SAFE:  ssh ... "cmd &" (just backgrounds one command)
+ */
+export function hasCommandChainWithAmpersand(command: string): boolean {
+	if (!isSshCommand(command)) return false;
+	if (isDetachedPattern(command)) return false;
+
+	const sshRange = findLastSshCommand(command);
+	if (!sshRange) return false;
+	const sshPart = command.slice(sshRange.start, sshRange.end);
+
+	// Find the quoted remote command
+	const quoteMatch = sshPart.match(/['"](.+?)['"]\s*$/s);
+	if (!quoteMatch) return false;
+
+	const quotedContent = quoteMatch[1];
+	// Risky: command chain followed by &
+	// e.g. "cd /path && python uvicorn 2>&1 &"  or "cmd1 && cmd2 &"
+	// Safe: just one command with & ("cmd &") or detached ("cmd > log 2>&1 & echo DONE")
+	const trimmed = quotedContent.trim();
+	// Detect && or ; followed by anything, then &
+	return /&&.+\s+&\s*$/.test(trimmed) || /;.+\s+&\s*$/.test(trimmed);
+}
+
+/**
+ * Transform a command to use detached SSH pattern.
+ * Removes trailing unquoted & and appends nohup wrapper.
+ *
+ * Before: ssh user@host 'kill 123' &
+ * After:  ssh user@host 'kill 123' nohup '' > /tmp/herdr-ssh.log 2>&1 & echo 'SSH_DETACHED'
+ *
+ * The && operators inside the quoted command are preserved.
+ */
+export function transformToDetached(
+	command: string,
+	config: { logFile?: string } = {},
+): string {
+	const { logFile = "/tmp/herdr-ssh.log" } = config;
+
+	if (isDetachedPattern(command)) return command;
+
+	const sshRange = findLastSshCommand(command);
+	if (!sshRange) return command;
+
+	const beforeSsh = command.slice(0, sshRange.start);
+	const sshPart = command.slice(sshRange.start, sshRange.end);
+	const afterSsh = command.slice(sshRange.end);
+
+	// Helper: find the position AFTER the closing quote of the last quoted arg
+	// Returns position AFTER the closing quote, or s.length if no quotes found.
+	function findClosingQuotePos(s: string): number {
+		for (let i = s.length - 1; i >= 0; i--) {
+			if (s[i] === "\\" && i > 0) {
+				i--;
+				continue;
+			}
+			if (s[i] === '"' || s[i] === "'") {
+				const cq = s[i];
+				let found = false;
+				for (let j = i - 1; j >= 0; j--) {
+					if (s[j] === "\\") {
+						j--;
+						continue;
+					}
+					if (s[j] === cq) {
+						found = true;
+						break;
+					}
+				}
+				if (found) return i + 1; // AFTER closing quote
+			}
+		}
+		return s.length;
+	}
+
+	// Helper: find the position OF the closing quote (excluding the quote itself)
+	function findClosingQuotePosExcl(s: string): number {
+		for (let i = s.length - 1; i >= 0; i--) {
+			if (s[i] === "\\" && i > 0) {
+				i--;
+				continue;
+			}
+			if (s[i] === '"' || s[i] === "'") {
+				const cq = s[i];
+				let found = false;
+				for (let j = i - 1; j >= 0; j--) {
+					if (s[j] === "\\") {
+						j--;
+						continue;
+					}
+					if (s[j] === cq) {
+						found = true;
+						break;
+					}
+				}
+				if (found) return i; // AT (not after) closing quote
+			}
+		}
+		return s.length;
+	}
+
+	// Pattern 1: bare & OUTSIDE the quoted remote command
+	// e.g. ssh host 'kill 123' &
+	// remoteCmdEnd1 includes the closing quote in sshPrefix
+	const remoteCmdEnd1 = findClosingQuotePos(sshPart);
+	const sshPrefix = sshPart.slice(0, remoteCmdEnd1).trimEnd();
+	const afterRemoteCmd = sshPart.slice(remoteCmdEnd1);
+	if (/^\s*&\s*$/.test(afterRemoteCmd.trim())) {
+		return (
+			beforeSsh +
+			sshPrefix +
+			` nohup '' > ${logFile} 2>&1 & echo 'SSH_DETACHED'` +
+			afterSsh
+		);
+	}
+
+	// Pattern 2: command chain with & INSIDE the quoted part
+	// e.g. ssh host "cmd1 && cmd2 &"  or  ssh host "cmd1 && cmd2 2>&1 &"
+	// Find opening quote to exclude closing quote from beforeQuote (needed for chain regex)
+	let openQuotePos = -1;
+	for (let i = 0; i < sshPart.length; i++) {
+		if (sshPart[i] === "'" || sshPart[i] === '"') {
+			openQuotePos = i;
+			break;
+		}
+	}
+	if (openQuotePos < 0) return command;
+
+	// Exclude closing quote so chain regex can match the & that precedes it
+	const remoteCmdEnd2 = findClosingQuotePosExcl(sshPart);
+	const beforeQuote = sshPart.slice(0, remoteCmdEnd2);
+
+	// Chain with 2>&1 redirect first (&& chains only — `;` chains inside quotes
+	// are left alone per contract: SSH completes normally for them)
+	const chainMatch2 = beforeQuote.match(/(.+?)&&\s*(.+?)\s+(2>&1)\s*&\s*$/);
+	if (chainMatch2) {
+		return (
+			beforeSsh +
+			chainMatch2[1] +
+			"&&" +
+			` nohup ${chainMatch2[2]} ${chainMatch2[3]} & echo 'SSH_DETACHED'"`
+		);
+	}
+
+	// Chain without 2>&1
+	const chainMatch = beforeQuote.match(/(.+?)&&\s*(.+?)\s*&\s*$/);
+	if (chainMatch) {
+		return (
+			beforeSsh +
+			chainMatch[1] +
+			"&&" +
+			` nohup ${chainMatch[2]} > ${logFile} 2>&1 & echo 'SSH_DETACHED'"`
+		);
+	}
+
+	return command;
+}
+
+/**
+ * Detect SSH in a bash command and return warning info.
+ */
+export interface SshDetection {
+	isSsh: boolean;
+	isDetached: boolean;
+	hasBareAmpersand: boolean;
+	/** Foreground SSH running a daemon-ish remote command with no timeout guard. */
+	needsTimeoutGuard: boolean;
+	suggestion: string;
+}
+
+export function detectSsh(command: string): SshDetection {
+	const ssh = isSshCommand(command);
+	const detached = ssh ? isDetachedPattern(command) : false;
+	const bare = ssh ? hasBareAmpersand(command) : false;
+	const needsTimeout = ssh ? isForegroundDaemonSsh(command) : false;
+
+	let suggestion = "";
+	if (ssh && !detached && bare) {
+		suggestion =
+			"Warning: trailing '&' outside quotes backgrounds SSH itself. Use nohup ... > /tmp/log 2>&1 & echo DONE.";
+	} else if (needsTimeout) {
+		suggestion = `Warning: foreground SSH running a long-lived remote command. Auto-wrapped with timeout ${getDefaultSshTimeoutSeconds()}s (set PI_HARNESS_SSH_TIMEOUT_S to change).`;
+	}
+
+	return {
+		isSsh: ssh,
+		isDetached: detached,
+		hasBareAmpersand: bare,
+		needsTimeoutGuard: needsTimeout,
+		suggestion,
+	};
+}
+
+// --- Foreground daemon-over-SSH timeout guard ---------------------------------
+//
+// Problem: `ssh -tt host "python -m worker --video | head -10"` runs a poller
+// daemon in the foreground. head -10 exits, the daemon swallows BrokenPipeError
+// and keeps ticking; ssh -tt holds the session until the whole remote pipeline
+// ends — which never happens. Observed: 1911.9s hang until manual abort.
+//
+// Solution: detect daemon-ish remote payloads without any timeout protection
+// and prefix the ssh invocation with `timeout Ns` so the local side is always
+// guaranteed to return.
+
+/** Long-running remote command patterns (pollers, servers, watchers). */
+const REMOTE_DAEMON_PATTERNS: RegExp[] = [
+	/\buvicorn\b/,
+	/\bgunicorn\b/,
+	/\bcelery\b/,
+	/\bflask\s+run\b/,
+	/\btail\s+-f\b/,
+	/\bnpm\s+(run\s+)?(dev|start)\b/,
+	/\bbun\s+(run\s+)?(dev|start)\b/,
+	/\byarn\s+(dev|start)\b/,
+	/\bnode\s+\S*(server|daemon)\S*/,
+	/--watch(\s|=)/,
+	/\bpython3?\s+-m\s+\S*(worker|daemon|server|bot|poller|scheduler|agent)\S*/,
+	/\buv\s+run\s+\S*(worker|daemon|server|bot|poller|scheduler|agent)\S*/,
+];
+
+export function getDefaultSshTimeoutSeconds(): number {
+	const raw = process.env.PI_HARNESS_SSH_TIMEOUT_S;
+	const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 300;
+}
+
+/**
+ * Extract the remote command payload of an ssh invocation (the quoted
+ * argument). Falls back to the whole ssh segment when unquoted.
+ */
+function extractRemotePayload(sshPart: string): string {
+	const m = sshPart.match(/["'](.+)["']/s);
+	return m ? m[1] : sshPart;
+}
+
+/**
+ * The ssh flag segment: everything before the quoted remote command.
+ * Used for host-side flag checks (-f, -o, ...) so that remote payload args
+ * like `tail -f` are not mistaken for ssh flags.
+ */
+function getSshFlagSegment(sshPart: string): string {
+	const quotePos = sshPart.search(/["']/);
+	return quotePos >= 0 ? sshPart.slice(0, quotePos) : sshPart;
+}
+
+/**
+ * Check if an SSH command runs a daemon-ish remote command in the
+ * foreground with no timeout protection anywhere (local or remote).
+ *
+ * RISKY:  ssh -tt host "cd app && python -m amos_worker --video 2>&1 | head -10"
+ * SAFE:   timeout 60s ssh host "python -m amos_worker --video"
+ * SAFE:   ssh host "timeout 30 python -m amos_worker --video"
+ * SAFE:   ssh host "nohup python -m amos_worker ... &" (detached patterns)
+ * SAFE:   ssh -f host "..." (ssh backgrounds itself)
+ */
+export function isForegroundDaemonSsh(command: string): boolean {
+	if (!isSshCommand(command)) return false;
+	if (isDetachedPattern(command)) return false;
+	if (hasBareAmpersand(command)) return false; // handled by detach transform
+	if (/\bnohup\b/.test(command)) return false;
+
+	const range = findLastSshCommand(command);
+	if (!range) return false;
+	const sshPart = command.slice(range.start, range.end);
+
+	// ssh -f: requests ssh itself to go to background before executing.
+	// Only inspect the flag segment — `tail -f` in the remote payload is NOT ssh -f.
+	const flagSegment = getSshFlagSegment(sshPart);
+	if (/(^|\s)-f(\s|$)/.test(flagSegment)) return false;
+
+	// Any timeout guard (local `timeout Ns ssh` or remote `timeout N cmd`)
+	if (/\btimeout\b/.test(command)) return false;
+
+	const payload = extractRemotePayload(sshPart);
+	// Remote-side backgrounding (`... &` inside quotes): SSH completes when the
+	// remote shell returns — per project convention this is the safe pattern.
+	if (/&\s*$/.test(payload.trim())) return false;
+
+	return REMOTE_DAEMON_PATTERNS.some((re) => re.test(payload));
+}
+
+/**
+ * Prefix the last ssh invocation with `timeout Ns` so the local bash call is
+ * guaranteed to return even if the remote daemon never exits.
+ *
+ * Before: echo 'x' | ssh -tt host "python -m amos_worker --video | head -10"
+ * After:  echo 'x' | timeout 300s ssh -tt host "python -m amos_worker --video | head -10"
+ */
+export function addSshTimeoutGuard(
+	command: string,
+	seconds: number = getDefaultSshTimeoutSeconds(),
+): string {
+	if (!Number.isFinite(seconds) || seconds <= 0) return command;
+	const range = findLastSshCommand(command);
+	if (!range) return command;
+	return (
+		command.slice(0, range.start) +
+		`timeout ${seconds}s ` +
+		command.slice(range.start)
+	);
+}