pi-better-background-tasks 0.1.18 → 0.2.1

package/README.md

@@ -18,6 +18,31 @@ Use `pi-better-background-tasks` when a command should keep running while the fo
 - Show active work in Pi's background-work navigator.
 - Flag running tasks with no observable output or completed poll as stalled.
 
+## Remote SSH
+
+Prefer structured `ssh` fields over hand-written `ssh` command lines. A remote
+spawn uses a durable tmux session by default, while a remote watch opens one
+direct SSH poll per interval and does not require tmux. The package keeps the
+same local metadata, logs, terminal statuses, callbacks, and `/reload` recovery
+for both.
+
+```json
+{
+  "name": "remote build",
+  "command": "npm run build",
+  "ssh": { "host": "build.example", "user": "deploy" },
+  "remote": { "workdir": "/srv/app" },
+  "timeout_seconds": 1800
+}
+```
+
+Tmux-backed spawn can install tmux non-interactively when the remote host allows
+it and fails closed with copy-pasteable setup guidance when it cannot. Set
+`remote.session=direct` only as an explicit escape hatch for short jobs: stop or
+timeout can terminate the local SSH client but the remote process may still be
+running. See the detailed usage notes for bootstrap policy, watch conditions,
+timeouts, and v1 non-goals.
+
 ## Install
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.1.18",
+  "version": "0.2.1",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
   "files": [
     "src/**/*.ts",
     "!src/**/*.test.ts",
+    "!src/test-support/**",
     "README.md"
   ],
   "peerDependencies": {

package/src/logs.ts

@@ -21,6 +21,12 @@ export function appendLine(logPath: string, line: string): void {
   appendFileSync(logPath, `${line}\n`);
 }
 
+export function appendTaskOutput(logPath: string, output: string): void {
+  if (!output) return;
+  mkdirSync(dirname(logPath), { recursive: true });
+  appendFileSync(logPath, output);
+}
+
 export function readLog(logPath: string, tailLines?: number): { text: string; truncated: boolean } {
   const requestedRows = tailLines && tailLines > 0 ? Math.floor(tailLines) : undefined;
   const tail = readBoundedTail(logPath, MAX_LOG_TAIL_READ_BYTES);

package/src/navigator-provider.ts

@@ -56,8 +56,8 @@ const provider: BackgroundWorkProvider = {
     const meta = readMeta(id);
     if (!meta) return { action: "missing", providerId: "background-tasks", id };
     if (meta.status === "running") {
-      const stopped = stopTask(piRef as ExtensionAPI, id);
-      return { action: "stopped", providerId: "background-tasks", id, status: stopped?.status };
+      void stopTask(piRef as ExtensionAPI, id);
+      return { action: "stopped", providerId: "background-tasks", id, status: "stopping" };
     }
     meta.dismissedAt = Date.now();
     writeMeta(meta);
@@ -104,7 +104,7 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
   return {
     providerId: "background-tasks",
     id: meta.id,
-    name: meta.name,
+    name: meta.name ?? (meta.ssh ? `${meta.ssh.target}${meta.remote?.session ? ` ${meta.remote.session}` : ""}` : undefined),
     status: meta.status,
     statusTone: toneForStatus(meta.status),
     kind: meta.kind === "command_watch" ? "watch" : "process",
@@ -134,6 +134,11 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     { label: "pgid", value: meta.pgid != null ? String(meta.pgid) : "-" },
     { label: "log", value: meta.logPath },
   ];
+  if (meta.ssh) metadata.push({ label: "remote", value: meta.ssh.target });
+  if (meta.remote?.session) metadata.push({ label: "remote mode", value: meta.remote.session });
+  if (meta.remote?.sessionName) metadata.push({ label: "remote session", value: meta.remote.sessionName });
+  if (meta.remote?.bootstrapMessage) metadata.push({ label: "remote setup", value: meta.remote.bootstrapMessage });
+  if (meta.remote?.warning) metadata.push({ label: "warning", value: meta.remote.warning });
   if (meta.deadlineAt) metadata.push({ label: "deadline", value: formatDuration(meta.deadlineAt - now) });
   if (meta.lastCheckedAt) metadata.push({ label: "checked", value: `${formatDuration(now - meta.lastCheckedAt)} ago` });
   if (meta.status === "running") {
@@ -187,6 +192,7 @@ function commandLabel(meta: BackgroundTaskMeta): string {
 }
 
 function compactCommandLabel(meta: BackgroundTaskMeta): string {
+  if (meta.ssh) return `${meta.ssh.target}${meta.remote?.session ? ` ${meta.remote.session}` : ""}`;
   const value = commandLabel(meta).trim();
   const parts = value.split(/\s+/).filter(Boolean);
   if (parts.length <= 3) return value;
@@ -196,6 +202,7 @@ function compactCommandLabel(meta: BackgroundTaskMeta): string {
 function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
   const parts = [];
   if (meta.cwd) parts.push(meta.cwd);
+  if (meta.remote?.session) parts.push(meta.remote.session);
   if (meta.pid != null) parts.push(`pid ${meta.pid}`);
   if (meta.lastExitCode !== undefined) parts.push(`exit ${meta.lastExitCode}`);
   return parts.length ? parts.join(" · ") : undefined;

package/src/process.ts

@@ -36,12 +36,17 @@ export function spawnCommand(spec: CommandSpec, logPath: string, detached: boole
   return { child, pgid: detached && child.pid ? child.pid : undefined };
 }
 
-export function runCommandOnce(spec: CommandSpec, maxBufferBytes = 1024 * 1024): Promise<CommandResult> {
+export function runCommandOnce(
+  spec: CommandSpec,
+  maxBufferBytes = 1024 * 1024,
+  timeoutMs?: number,
+): Promise<CommandResult> {
   validateCommandSpec(spec);
   const startedAt = Date.now();
   const child = spawnArgs(spec, false, ["ignore", "pipe", "pipe"]);
   let stdout = "";
   let stderr = "";
+  let timedOut = false;
   child.stdout?.on("data", (chunk: Buffer) => {
     if (Buffer.byteLength(stdout) < maxBufferBytes) stdout += chunk.toString("utf8");
   });
@@ -49,9 +54,26 @@ export function runCommandOnce(spec: CommandSpec, maxBufferBytes = 1024 * 1024):
     if (Buffer.byteLength(stderr) < maxBufferBytes) stderr += chunk.toString("utf8");
   });
   return new Promise((resolve, reject) => {
-    child.on("error", reject);
+    const timeout = timeoutMs === undefined ? undefined : setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, Math.max(1, timeoutMs));
+    timeout?.unref();
+    child.on("error", (error) => {
+      if (timeout) clearTimeout(timeout);
+      reject(error);
+    });
     child.on("close", (exitCode, signal) => {
-      resolve({ exitCode, signal, stdout, stderr, startedAt, endedAt: Date.now() });
+      if (timeout) clearTimeout(timeout);
+      resolve({
+        exitCode,
+        signal,
+        stdout,
+        stderr,
+        startedAt,
+        endedAt: Date.now(),
+        ...(timedOut ? { timedOut: true } : {}),
+      });
     });
   });
 }

package/src/registry.ts

@@ -9,7 +9,11 @@ const metaCache = new Map<string, BackgroundTaskMeta>();
 const metaChangedListeners = new Set<() => void>();
 
 export function baseDir(): string {
-  return join(tmpdir(), "pi-better-background-tasks");
+  const vitestPoolId = process.env.VITEST_POOL_ID;
+  const directory = vitestPoolId && /^\d+$/.test(vitestPoolId)
+    ? `pi-better-background-tasks-vitest-${vitestPoolId}`
+    : "pi-better-background-tasks";
+  return join(tmpdir(), directory);
 }
 
 export function tasksDir(): string {