ugly-app 0.1.809 → 0.1.810

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.809";
+export declare const CLI_VERSION = "0.1.810";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.809";
+export const CLI_VERSION = "0.1.810";
 //# sourceMappingURL=version.js.map

package/dist/native/facades/task.d.ts

@@ -28,6 +28,30 @@ export interface TaskFacade {
         params?: unknown;
         id?: string;
     }): Promise<TaskHandle>;
+    /**
+     * Idempotent upsert of a background task by stable `id`. Reuses the running task
+     * when its bundle (`entry`) matches; otherwise replaces it — stops the stale/dead
+     * one, starts fresh, and waits until it is ready — then returns the handle. Use
+     * this instead of hand-rolling enum→compare→stop→start: it also absorbs the host
+     * stop→start-same-id exit race (a killed child's async `exit`, keyed by id, can
+     * otherwise clobber the freshly started task to 'exited'). `reused` is false when
+     * a NEW child was started — signalling the caller to re-establish per-task
+     * `listen()` subscriptions (a replaced task drops the old host listener).
+     */
+    ensure(opts: {
+        id: string;
+        entry: string;
+        kind?: string;
+        label?: string;
+        params?: unknown;
+        /** Max wait for the fresh task to report ready (default 20s). */
+        readyTimeoutMs?: number;
+        /** Readiness poll interval (default 100ms). */
+        pollMs?: number;
+    }): Promise<{
+        handle: TaskHandle;
+        reused: boolean;
+    }>;
     /** List this app's background tasks (origin-scoped on the host). */
     enum(): Promise<TaskInfo[]>;
     /** Get a handle to an already-running task by id without spawning. */
@@ -52,6 +76,6 @@ type Subscribe = (event: string, cb: (data: unknown) => void) => () => void;
  *   listen→ subscribe('task.event:'+id)  (host fans events out as { event, data })
  * Assembled client-side so it's identical local (desktop) or proxied (mobile/web).
  */
-export declare function createTaskFacade(invoke: Invoke, subscribe: Subscribe, ensure?: () => Promise<void>): TaskFacade;
+export declare function createTaskFacade(invoke: Invoke, subscribe: Subscribe, whenReady?: () => Promise<void>): TaskFacade;
 export {};
 //# sourceMappingURL=task.d.ts.map

package/dist/native/facades/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/native/facades/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACpE,0FAA0F;IAC1F,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE,gEAAgE;IAChE,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,IAAI,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxB,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5B,sEAAsE;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/B,oCAAoC;IACpC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChF,yBAAyB;IACzB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACjD;AAKD,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AACtE,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;AAE5E;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CAgC/G"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/native/facades/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACpE,0FAA0F;IAC1F,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE,gEAAgE;IAChE,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,IAAI,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE;QACX,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,iEAAiE;QACjE,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,+CAA+C;QAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACrD,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5B,sEAAsE;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/B,oCAAoC;IACpC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChF,yBAAyB;IACzB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACjD;AAKD,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AACtE,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;AAE5E;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CA6ElH"}

package/dist/native/facades/task.js

@@ -18,13 +18,31 @@ export function taskEntryUrl(name, buildId, origin) {
  *   listen→ subscribe('task.event:'+id)  (host fans events out as { event, data })
  * Assembled client-side so it's identical local (desktop) or proxied (mobile/web).
  */
-export function createTaskFacade(invoke, subscribe, ensure) {
+export function createTaskFacade(invoke, subscribe, whenReady) {
     const listen = (id, onEvent) => subscribe(`task.event:${id}`, (d) => {
         const f = (d ?? {});
         onEvent(f.event ?? 'event', f.data);
     });
     const call = (id, method, payload) => invoke('task.call', { id, method, payload });
     const stop = (id) => invoke('task.stop', { id });
+    const enumTasks = async () => (await invoke('task.enum', undefined)).tasks;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    // Poll enum until the task reports 'running'. Throws on a terminal 'exited'/'error'
+    // (a genuine startup failure — or, transiently, the stop→start clobber the caller
+    // retries past) and on timeout.
+    const waitRunning = async (id, timeoutMs, pollMs) => {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const t = (await enumTasks()).find((x) => x.id === id);
+            if (t?.status === 'running')
+                return;
+            if (t && (t.status === 'exited' || t.status === 'error'))
+                throw new Error(`task failed to start: ${t.status}`);
+            if (Date.now() >= deadline)
+                throw new Error('task did not become ready in time');
+            await sleep(pollMs);
+        }
+    };
     const handle = (id) => ({
         id,
         listen: (onEvent) => listen(id, onEvent),
@@ -33,13 +51,51 @@ export function createTaskFacade(invoke, subscribe, ensure) {
     });
     return {
         async start(opts) {
-            if (ensure)
-                await ensure();
+            if (whenReady)
+                await whenReady();
             const r = (await invoke('task.start', opts));
             return handle(r.id);
         },
+        async ensure(opts) {
+            const { id, entry, kind, label, params } = opts;
+            const readyTimeoutMs = opts.readyTimeoutMs ?? 20_000;
+            const pollMs = opts.pollMs ?? 100;
+            const existing = (await enumTasks()).find((t) => t.id === id);
+            const alive = !!existing && existing.status !== 'exited' && existing.status !== 'error';
+            // Reuse a healthy task whose bundle matches. `entry` pins the buildId, so a
+            // task left from a prior deploy (different entry) is never reused.
+            if (alive && existing.entry === entry)
+                return { handle: handle(id), reused: true };
+            // Replace. Stop→start on the SAME id races the host: `stop` kills the old child
+            // asynchronously and its late `exit` (keyed by id) can fire AFTER the fresh task
+            // registers, clobbering it to 'exited'. So stop, let the old child die (settle),
+            // then start; retry with a growing settle if a slow-dying child still clobbers.
+            if (existing) {
+                try {
+                    await stop(id);
+                }
+                catch { /* already gone */ }
+            }
+            const settles = alive ? [350, 900, 1800] : [0];
+            let lastErr;
+            for (const settleMs of settles) {
+                if (settleMs > 0)
+                    await sleep(settleMs);
+                if (whenReady)
+                    await whenReady();
+                await invoke('task.start', { id, entry, kind, label, params });
+                try {
+                    await waitRunning(id, readyTimeoutMs, pollMs);
+                    return { handle: handle(id), reused: false };
+                }
+                catch (e) {
+                    lastErr = e; // likely the clobber — retry after a longer settle
+                }
+            }
+            throw lastErr;
+        },
         async enum() {
-            return (await invoke('task.enum', undefined)).tasks;
+            return enumTasks();
         },
         attach: (id) => handle(id),
         call,

package/dist/native/facades/task.js.map

@@ -1 +1 @@
-{"version":3,"file":"task.js","sourceRoot":"","sources":["../../../src/native/facades/task.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe,EAAE,MAAe;IACzE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChF,OAAO,GAAG,IAAI,IAAI,OAAO,UAAU,IAAI,KAAK,CAAC;AAC/C,CAAC;AAwCD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,SAAoB,EAAE,MAA4B;IACjG,MAAM,MAAM,GAAG,CAAC,EAAU,EAAE,OAA+C,EAAgB,EAAE,CAC3F,SAAS,CAAC,cAAc,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE;QAClC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAuC,CAAC;QAC1D,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IACL,MAAM,IAAI,GAAG,CAAI,EAAU,EAAE,MAAc,EAAE,OAAiB,EAAc,EAAE,CAC5E,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAe,CAAC;IAC7D,MAAM,IAAI,GAAG,CAAC,EAAU,EAAiC,EAAE,CACzD,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,CAAkC,CAAC;IAE/D,MAAM,MAAM,GAAG,CAAC,EAAU,EAAc,EAAE,CAAC,CAAC;QAC1C,EAAE;QACF,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC;QACxC,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC;QACpD,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;KACrB,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,IAAI;YACd,IAAI,MAAM;gBAAE,MAAM,MAAM,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAmB,CAAC;YAC/D,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,KAAK,CAAC,IAAI;YACR,OAAQ,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAA2B,CAAC,KAAK,CAAC;QACjF,CAAC;QACD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,IAAI;QACJ,MAAM;QACN,IAAI;KACL,CAAC;AACJ,CAAC"}
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../../src/native/facades/task.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.809",
+  "version": "0.1.810",
   "type": "module",
   "comment:files": "Allowlist what ships to npm. dist = runtime; src = sourcemap targets (dist/*.js.map reference ../../src/); templates = CLI scaffold. Everything else at repo root (.pgdata local Postgres, coverage, assets/icons sources, test/, test-results/) is excluded by omission. The !negations strip the scaffold's installed deps + cruft (templates/node_modules is 200MB+ and must never ship). package.json/README/LICENSE ship automatically.",
   "files": [

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.809";
+export const CLI_VERSION = "0.1.810";

package/src/native/facades/task.test.ts

@@ -72,4 +72,66 @@ describe('createTaskFacade', () => {
     expect(invoke).toHaveBeenCalledWith('task.call', { id: 'task_9', method: 'ping', payload: undefined });
     expect(invoke).toHaveBeenCalledWith('task.stop', { id: 'task_9' });
   });
+
+  const rec = (over: Partial<{ status: string; entry: string }>) => ({
+    id: 'coding:s', kind: 'coding', label: 'x', origin: 'o', startedAt: 1,
+    status: 'running', entry: 'E1', ...over,
+  });
+
+  it('ensure reuses a running task whose entry matches (no stop/start)', async () => {
+    const invoke = vi.fn(async (ch: string) =>
+      ch === 'task.enum' ? { tasks: [rec({ entry: 'E1' })] } : undefined);
+    const r = await createTaskFacade(invoke, vi.fn()).ensure({ id: 'coding:s', entry: 'E1', kind: 'coding' });
+    expect(r.reused).toBe(true);
+    expect(r.handle.id).toBe('coding:s');
+    expect(invoke).not.toHaveBeenCalledWith('task.stop', expect.anything());
+    expect(invoke).not.toHaveBeenCalledWith('task.start', expect.anything());
+  });
+
+  it('ensure replaces a stale-entry task: stop old, start fresh, reused=false', async () => {
+    let started = false;
+    const invoke = vi.fn(async (ch: string) => {
+      if (ch === 'task.enum') return { tasks: [rec({ entry: started ? 'E2' : 'E1' })] };
+      if (ch === 'task.stop') return { stopped: true };
+      if (ch === 'task.start') { started = true; return { id: 'coding:s' }; }
+      return undefined;
+    });
+    const r = await createTaskFacade(invoke, vi.fn())
+      .ensure({ id: 'coding:s', entry: 'E2', kind: 'coding', readyTimeoutMs: 2000, pollMs: 1 });
+    expect(r.reused).toBe(false);
+    expect(invoke).toHaveBeenCalledWith('task.stop', { id: 'coding:s' });
+    expect(invoke).toHaveBeenCalledWith('task.start', expect.objectContaining({ id: 'coding:s', entry: 'E2' }));
+  });
+
+  it('ensure starts fresh when no task exists, without stopping', async () => {
+    let started = false;
+    const invoke = vi.fn(async (ch: string) => {
+      if (ch === 'task.enum') return { tasks: started ? [rec({ entry: 'E1' })] : [] };
+      if (ch === 'task.start') { started = true; return { id: 'coding:s' }; }
+      return undefined;
+    });
+    const r = await createTaskFacade(invoke, vi.fn()).ensure({ id: 'coding:s', entry: 'E1', pollMs: 1 });
+    expect(r.reused).toBe(false);
+    expect(invoke).not.toHaveBeenCalledWith('task.stop', expect.anything());
+  });
+
+  it('ensure retries past a transient exited (the stop→start clobber race)', async () => {
+    let starts = 0;
+    const invoke = vi.fn(async (ch: string) => {
+      if (ch === 'task.enum') {
+        // stale E1 until first start; the first fresh task is clobbered to 'exited'
+        // (race), the second start lands 'running'.
+        if (starts === 0) return { tasks: [rec({ entry: 'E1' })] };
+        if (starts === 1) return { tasks: [rec({ entry: 'E2', status: 'exited' })] };
+        return { tasks: [rec({ entry: 'E2', status: 'running' })] };
+      }
+      if (ch === 'task.stop') return { stopped: true };
+      if (ch === 'task.start') { starts += 1; return { id: 'coding:s' }; }
+      return undefined;
+    });
+    const r = await createTaskFacade(invoke, vi.fn())
+      .ensure({ id: 'coding:s', entry: 'E2', kind: 'coding', readyTimeoutMs: 5000, pollMs: 1 });
+    expect(r.reused).toBe(false);
+    expect(starts).toBe(2); // clobbered once, succeeded on retry
+  });
 });

package/src/native/facades/task.ts

@@ -32,6 +32,27 @@ export interface TaskFacade {
     params?: unknown;
     id?: string;
   }): Promise<TaskHandle>;
+  /**
+   * Idempotent upsert of a background task by stable `id`. Reuses the running task
+   * when its bundle (`entry`) matches; otherwise replaces it — stops the stale/dead
+   * one, starts fresh, and waits until it is ready — then returns the handle. Use
+   * this instead of hand-rolling enum→compare→stop→start: it also absorbs the host
+   * stop→start-same-id exit race (a killed child's async `exit`, keyed by id, can
+   * otherwise clobber the freshly started task to 'exited'). `reused` is false when
+   * a NEW child was started — signalling the caller to re-establish per-task
+   * `listen()` subscriptions (a replaced task drops the old host listener).
+   */
+  ensure(opts: {
+    id: string;
+    entry: string;
+    kind?: string;
+    label?: string;
+    params?: unknown;
+    /** Max wait for the fresh task to report ready (default 20s). */
+    readyTimeoutMs?: number;
+    /** Readiness poll interval (default 100ms). */
+    pollMs?: number;
+  }): Promise<{ handle: TaskHandle; reused: boolean }>;
   /** List this app's background tasks (origin-scoped on the host). */
   enum(): Promise<TaskInfo[]>;
   /** Get a handle to an already-running task by id without spawning. */
@@ -59,7 +80,7 @@ type Subscribe = (event: string, cb: (data: unknown) => void) => () => void;
  *   listen→ subscribe('task.event:'+id)  (host fans events out as { event, data })
  * Assembled client-side so it's identical local (desktop) or proxied (mobile/web).
  */
-export function createTaskFacade(invoke: Invoke, subscribe: Subscribe, ensure?: () => Promise<void>): TaskFacade {
+export function createTaskFacade(invoke: Invoke, subscribe: Subscribe, whenReady?: () => Promise<void>): TaskFacade {
   const listen = (id: string, onEvent: (event: string, data: unknown) => void): (() => void) =>
     subscribe(`task.event:${id}`, (d) => {
       const f = (d ?? {}) as { event?: string; data?: unknown };
@@ -69,6 +90,22 @@ export function createTaskFacade(invoke: Invoke, subscribe: Subscribe, ensure?:
     invoke('task.call', { id, method, payload }) as Promise<R>;
   const stop = (id: string): Promise<{ stopped: boolean }> =>
     invoke('task.stop', { id }) as Promise<{ stopped: boolean }>;
+  const enumTasks = async (): Promise<TaskInfo[]> =>
+    ((await invoke('task.enum', undefined)) as { tasks: TaskInfo[] }).tasks;
+  const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+  // Poll enum until the task reports 'running'. Throws on a terminal 'exited'/'error'
+  // (a genuine startup failure — or, transiently, the stop→start clobber the caller
+  // retries past) and on timeout.
+  const waitRunning = async (id: string, timeoutMs: number, pollMs: number): Promise<void> => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const t = (await enumTasks()).find((x) => x.id === id);
+      if (t?.status === 'running') return;
+      if (t && (t.status === 'exited' || t.status === 'error')) throw new Error(`task failed to start: ${t.status}`);
+      if (Date.now() >= deadline) throw new Error('task did not become ready in time');
+      await sleep(pollMs);
+    }
+  };
 
   const handle = (id: string): TaskHandle => ({
     id,
@@ -79,12 +116,41 @@ export function createTaskFacade(invoke: Invoke, subscribe: Subscribe, ensure?:
 
   return {
     async start(opts) {
-      if (ensure) await ensure();
+      if (whenReady) await whenReady();
       const r = (await invoke('task.start', opts)) as { id: string };
       return handle(r.id);
     },
+    async ensure(opts) {
+      const { id, entry, kind, label, params } = opts;
+      const readyTimeoutMs = opts.readyTimeoutMs ?? 20_000;
+      const pollMs = opts.pollMs ?? 100;
+      const existing = (await enumTasks()).find((t) => t.id === id);
+      const alive = !!existing && existing.status !== 'exited' && existing.status !== 'error';
+      // Reuse a healthy task whose bundle matches. `entry` pins the buildId, so a
+      // task left from a prior deploy (different entry) is never reused.
+      if (alive && existing.entry === entry) return { handle: handle(id), reused: true };
+      // Replace. Stop→start on the SAME id races the host: `stop` kills the old child
+      // asynchronously and its late `exit` (keyed by id) can fire AFTER the fresh task
+      // registers, clobbering it to 'exited'. So stop, let the old child die (settle),
+      // then start; retry with a growing settle if a slow-dying child still clobbers.
+      if (existing) { try { await stop(id); } catch { /* already gone */ } }
+      const settles = alive ? [350, 900, 1800] : [0];
+      let lastErr: unknown;
+      for (const settleMs of settles) {
+        if (settleMs > 0) await sleep(settleMs);
+        if (whenReady) await whenReady();
+        await invoke('task.start', { id, entry, kind, label, params });
+        try {
+          await waitRunning(id, readyTimeoutMs, pollMs);
+          return { handle: handle(id), reused: false };
+        } catch (e) {
+          lastErr = e; // likely the clobber — retry after a longer settle
+        }
+      }
+      throw lastErr;
+    },
     async enum() {
-      return ((await invoke('task.enum', undefined)) as { tasks: TaskInfo[] }).tasks;
+      return enumTasks();
     },
     attach: (id) => handle(id),
     call,