@amalgm/automations 0.3.2 → 0.4.0

package/AXIOMS.md

@@ -129,3 +129,14 @@
     action or process results become an explicit byte count plus bounded JSON
     preview before transport, so output can never strand a run outside the
     ledger it is meant to update.
+44. Agent onboarding delegates identity and runtime lifecycle to Shell and
+    proves Automations access with a successful read before declaring the
+    connection ready.
+45. A machine claims work only after notification coverage is ready, on a wakeup,
+    or while draining previously discovered work; idle machines never poll.
+46. Every run is committed before its wakeup, and every Fly host observes the
+    same private database notifications regardless of where admission occurred.
+47. Retry and expired-lease wakeups follow the earliest durable eligibility time
+    for that user and machine; a notification is never proof of execution.
+48. Losing upstream notification coverage closes downstream streams, and every
+    reconnect checks retained work before becoming idle again.

package/PURPOSE.md

@@ -27,6 +27,15 @@ The product has two composable halves over that one state:
   needs to know whether a machine is online: an unclaimed run is the complete
   offline queue.
 
+The local worker is idle when there is no work. It opens one authenticated
+HTTPS notification stream, claims retained runs when that stream becomes ready,
+and drains work when notified. Committed Supabase changes wake every Fly host;
+each host forwards only to the owning machine and schedules the next durable
+retry or lease deadline. Notifications carry no workflow data and never replace
+the run ledger. Reconnecting re-establishes notification coverage before checking
+the ledger. Connection health and active execution leases have bounded timers;
+idle machines have no periodic work-claim timer.
+
 The agent CLI is the command-line projection of the same task-level command
 surface as MCP: create, list, get, update, delete, and run-now. Each command
 accepts the same JSON object as its corresponding MCP tool and returns the same
@@ -38,6 +47,15 @@ CLI sees only the local runtime admission token. The standalone adapter may be
 composed over an already-bound SDK for tests and other hosts, but it never owns
 automation lifecycle or authorization rules.
 
+The portable Automations skill guides an agent from installation and Google
+sign-in to a verified Automations connection, then back to the user's requested
+work. Setup uses Shell's public commands and the existing browser approval;
+the skill never becomes an authentication implementation. It reuses a working
+connection, distinguishes account approval from runtime readiness, and helps
+the user reach aayush@amalgm.ai with bounded, redacted diagnostic evidence when
+the failing boundary cannot be repaired. The packaged skill is the source for
+installed copies and public setup/support guidance.
+
 The CLI is global configuration control, not directory-local state. The agent
 or person creating an automation may invoke it from any directory; the selected
 machine and the persisted workflow decide where effects occur later. A process

package/README.md

@@ -47,7 +47,10 @@ the API request.
 - `@amalgm/automations/host`: standalone Fly service composition.
 - `amalgm-automations`: CLI adapter.
 - `skills/amalgm-automations`: portable agent skill for operating either the
-  MCP or global CLI surface safely.
+  MCP or global CLI surface, including installation, Google sign-in, runtime
+  readiness, troubleshooting, and support. The packaged skill is the source
+  for installed copies; its [setup and support reference](skills/amalgm-automations/references/setup-and-support.md)
+  supplies the public onboarding guidance.
 
 ## Agent CLI
 
@@ -200,6 +203,7 @@ The machine execution API is:
 ```text
 POST  /v1/machine/runs/claim
 PATCH /v1/machine/runs/:runId
+GET   /v1/machine/runs/notifications
 ```
 
 Public webhook admission uses the URL returned on each webhook trigger:
@@ -218,13 +222,41 @@ The target is never accepted in a machine request. It comes from the verified
 access token. Run leases expire and are safely reclaimable; terminal updates
 must present the active lease token.
 
+The machine worker opens the authenticated HTTPS notification stream before
+its first claim. `ready` and `wake` events cause it to drain retained work;
+an idle worker has no polling interval. The stream sends a comment every
+30 seconds to detect broken connections; comments never cause a claim or a
+database read. Streams reconnect with fresh authorization at token expiry
+(at most five minutes), and reconnect checks recover missed notifications.
+
+Each Fly host subscribes to the same service-only Supabase Broadcast topic.
+Run inserts and eligibility changes publish small owner/target wakeups from
+the database transaction. Fly re-reads the earliest retry/lease deadline only
+when a target connects, changes, or reaches that deadline. Losing the database
+subscription closes the machine streams so they reconnect and catch up.
+Cron scheduling remains hosted; no schedule timer runs on the user's machine.
+
+Rollout order: apply the product migrations, deploy the Fly host, publish the
+SDK, then release Shell with that exact SDK version. Shell wires
+`notifications: runs.notifications` into `createAutomationMachineRunner`.
+The polling option and `AMALGM_AUTOMATIONS_POLL_INTERVAL_MS` are removed.
+Existing installed Shell releases keep their old behavior until updated.
+
 ## Verification
 
 ```bash
 npm run verify
 TEST_DATABASE_URL=postgres://... npm run test:supabase
+npm run test:notifications
 npm pack --dry-run
 ```
 
+`test:supabase` requires an empty disposable Postgres database; its fixture
+records the Supabase Broadcast boundary inside the same transaction.
+`test:notifications` requires Node.js 22+, Docker, and Supabase CLI 2.26.9
+(also pinned in CI). It starts and removes its own local Supabase project,
+using real database Broadcast and two HTTP hosts to verify delivery, idle
+behavior, offline catch-up, retry deadlines, and abandoned claims.
+
 See [PURPOSE.md](./PURPOSE.md) and [AXIOMS.md](./AXIOMS.md) for the governing
 ownership and behavior laws.

package/dist/host/auth.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { authorizeMachineResource, } from '@amalgm/core/authorization';
-import { calculateJwkThumbprint, createRemoteJWKSet, decodeProtectedHeader, importJWK, jwtVerify, } from 'jose';
+import { calculateJwkThumbprint, createRemoteJWKSet, decodeProtectedHeader, decodeJwt, importJWK, jwtVerify, } from 'jose';
 import { ForbiddenError } from '../src/errors.js';
 export function createAutomationsAuthenticators(options) {
     const jwks = createRemoteJWKSet(new URL(`${options.issuer}/.well-known/jwks.json`));
@@ -28,10 +28,13 @@ export function createAutomationsAuthenticators(options) {
         },
         machine: async (request) => {
             const principal = await authorize(request, options.issuer, 'runs:execute', ports);
+            // The exact token above has already passed Core's signature/lifetime checks.
+            const claims = decodeJwt(request.headers.get('authorization').trim().split(/\s+/)[1]);
             return {
                 userId: principal.userId,
                 computerId: principal.computerId,
                 scopes: automationScopes(principal.scopes),
+                authorizationExpiresAt: claims.exp * 1000,
             };
         },
     });

package/dist/host/main.js

@@ -12,6 +12,8 @@ import { WebhookEndpoints } from '../src/webhook.js';
 import { createAutomationsAuthenticators } from './auth.js';
 import { automationsHostConfig } from './config.js';
 import { createAutomationsHost } from './server.js';
+import { createMachineRunNotifications } from '../src/machine-notifications.js';
+import { subscribeToRunChanges } from './notifications.js';
 const config = automationsHostConfig();
 const supabase = createClient(config.supabaseUrl, config.supabaseServiceRoleKey, {
     auth: { persistSession: false, autoRefreshToken: false },
@@ -27,9 +29,15 @@ const controlApi = createAutomationApi({
     authenticate: authentication.control,
 });
 const machineRepository = new SupabaseMachineRunRepository(supabase);
+const notifications = createMachineRunNotifications({
+    wakeDelay: (userId, computerId) => machineRepository.wakeDelay(userId, computerId),
+    log,
+});
+const closeNotifications = subscribeToRunChanges(supabase, notifications);
 const machineApi = createMachineRunsApi({
     authenticate: authentication.machine,
     runsFor: (principal) => createMachineRuns(machineRepository, principal),
+    notifications,
 });
 const eventsApi = createAutomationEventsApi({
     delivery,
@@ -46,7 +54,7 @@ const host = createAutomationsHost({
 });
 host.server.listen(config.port, '0.0.0.0', () => log('host.ready', { port: config.port }));
 for (const signal of ['SIGINT', 'SIGTERM']) {
-    process.once(signal, () => void host.close().finally(() => process.exit(0)));
+    process.once(signal, () => void closeNotifications().then(() => host.close()).finally(() => process.exit(0)));
 }
 function log(event, details = {}) {
     console.log(JSON.stringify({ service: 'amalgm-automations', event, ...details }));

package/dist/host/notifications.d.ts

@@ -0,0 +1,4 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { MachineRunNotifications } from '../src/machine-notifications.js';
+/** One private database subscription per Fly host, shared by its machine streams. */
+export declare function subscribeToRunChanges(supabase: SupabaseClient, notifications: MachineRunNotifications): () => Promise<void>;

package/dist/host/notifications.js

@@ -0,0 +1,19 @@
+/** One private database subscription per Fly host, shared by its machine streams. */
+export function subscribeToRunChanges(supabase, notifications) {
+    const channel = supabase.channel('amalgm:automations:runs', { config: { private: true } })
+        .on('broadcast', { event: 'changed' }, ({ payload }) => {
+        if (typeof payload?.userId === 'string' && typeof payload?.targetId === 'string') {
+            notifications.changed(payload.userId, payload.targetId);
+        }
+    })
+        .subscribe((status) => {
+        if (status === 'SUBSCRIBED')
+            notifications.connected();
+        else
+            notifications.disconnected();
+    });
+    return async () => {
+        notifications.close();
+        await supabase.removeChannel(channel);
+    };
+}

package/dist/host/server.js

@@ -1,7 +1,9 @@
 import { createServer } from 'node:http';
+import { once } from 'node:events';
 import { publicResourceRequestUrl } from '@amalgm/core/authorization';
 export function createAutomationsHost(options) {
     const log = options.log ?? (() => { });
+    const requests = new Set();
     let scheduling = null;
     const tick = () => {
         if (scheduling)
@@ -14,34 +16,48 @@ export function createAutomationsHost(options) {
     timer.unref();
     tick();
     const server = createServer(async (incoming, outgoing) => {
+        const controller = new AbortController();
+        requests.add(controller);
+        const abort = () => controller.abort();
+        outgoing.once('close', abort);
         try {
             if (incoming.url === '/healthz')
-                return send(outgoing, Response.json({ ok: true }));
-            const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024);
+                return await send(outgoing, Response.json({ ok: true }), controller.signal);
+            const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024, controller.signal);
             const pathname = new URL(request.url).pathname;
             const api = pathname.startsWith('/e/') && options.eventsApi
                 ? options.eventsApi
                 : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
-            await send(outgoing, await api(request));
+            await send(outgoing, await api(request), controller.signal);
         }
         catch (error) {
+            if (controller.signal.aborted)
+                return;
             log('request.failed', { error: safe(error) });
+            if (outgoing.headersSent)
+                return outgoing.destroy();
             const status = error instanceof HostRequestError ? error.status : 500;
             await send(outgoing, Response.json({
                 error: status === 500 ? 'Automations service failed' : error instanceof Error ? error.message : String(error),
-            }, { status }));
+            }, { status }), controller.signal);
+        }
+        finally {
+            outgoing.removeListener('close', abort);
+            requests.delete(controller);
         }
     });
     return {
         server,
         async close() {
             clearInterval(timer);
+            for (const request of requests)
+                request.abort();
             await scheduling;
             await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
         },
     };
 }
-async function webRequest(request, publicOrigin, maximumBodyBytes) {
+async function webRequest(request, publicOrigin, maximumBodyBytes, signal) {
     const chunks = [];
     let size = 0;
     for await (const value of request) {
@@ -55,6 +71,7 @@ async function webRequest(request, publicOrigin, maximumBodyBytes) {
     return new Request(publicResourceRequestUrl(publicOrigin, request.url ?? '/'), {
         method: request.method ?? 'GET',
         headers: request.headers,
+        signal,
         ...(body.length ? { body } : {}),
     });
 }
@@ -65,8 +82,30 @@ class HostRequestError extends Error {
         this.status = status;
     }
 }
-async function send(response, source) {
+async function send(response, source, signal) {
     response.writeHead(source.status, Object.fromEntries(source.headers));
-    response.end(Buffer.from(await source.arrayBuffer()));
+    response.flushHeaders();
+    const reader = source.body?.getReader();
+    const abort = () => {
+        void reader?.cancel().catch(() => { });
+        response.destroy();
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        signal.throwIfAborted();
+        while (reader) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!response.write(value))
+                await once(response, 'drain', { signal });
+        }
+        response.end();
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        await reader?.cancel().catch(() => { });
+        reader?.releaseLock();
+    }
 }
 const safe = (error) => (error instanceof Error ? error.message : String(error)).slice(0, 500);

package/dist/src/cli/run.d.ts

@@ -8,6 +8,6 @@ export interface AutomationCliIo extends AutomationCliInputPorts {
     stdout?: Output;
     stderr?: Output;
 }
-export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
+export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nSetup and support:\n  Already connected? Reuse the running Amalgm Shell.\n  First login: amalgm login --no-open\n    Open the printed link, sign in with Google, and approve this computer.\n    Keep the login process running; it hosts Shell after approval.\n  Check: amalgm status --user EMAIL\n  Resume a registered computer: amalgm run --user EMAIL\n  Verify access: amalgm automations list --user EMAIL --input '{\"limit\":1}'\n  No local installation? https://amalgm.ai/setup\n  Support: aayush@amalgm.ai\n  Never copy private connection credentials into a command or support email.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
 export declare function runAutomationCli(argv: string[], backend: AutomationCrud | AutomationCommands, io?: AutomationCliIo): Promise<number>;
 export {};

package/dist/src/cli/run.js

@@ -20,6 +20,18 @@ Input is one JSON object with the corresponding MCP tool's fields. Commands
 without options receive {}. Output is one JSON success or error envelope.
 Use --stdin when input contains credentials such as a webhook signing secret.
 
+Setup and support:
+  Already connected? Reuse the running Amalgm Shell.
+  First login: amalgm login --no-open
+    Open the printed link, sign in with Google, and approve this computer.
+    Keep the login process running; it hosts Shell after approval.
+  Check: amalgm status --user EMAIL
+  Resume a registered computer: amalgm run --user EMAIL
+  Verify access: amalgm automations list --user EMAIL --input '{"limit":1}'
+  No local installation? https://amalgm.ai/setup
+  Support: aayush@amalgm.ai
+  Never copy private connection credentials into a command or support email.
+
 Workflow step lanes:
   version 1  action-only: {"id":"...","actionId":"product.action","input":{...}}
   version 2  action, command, or script steps:

package/dist/src/index.d.ts

@@ -19,6 +19,7 @@ export { SupabaseMachineRunRepository, type MachineRpcClient } from './supabase-
 export { createMachineRuns } from './machine.js';
 export type { AutomationMachinePrincipal, ClaimedAutomationRun, MachineRunRepository, MachineRuns, MachineRunUpdate, } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
+export { createMachineRunNotifications, type MachineRunNotifications } from './machine-notifications.js';
 export { createMachineRunsClient, type AutomationRequestHeaders } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan, type AutomationActionPort, type AutomationProcessExecution, type AutomationProcessPort, type AutomationRunExecutorOptions, } from './executor.js';
 export { createNodeAutomationProcessHost, type NodeAutomationProcessHostOptions, } from './node-process-host.js';

package/dist/src/index.js

@@ -24,6 +24,7 @@ export { SupabaseStore } from './supabase-store.js';
 export { SupabaseMachineRunRepository } from './supabase-machine.js';
 export { createMachineRuns } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
+export { createMachineRunNotifications } from './machine-notifications.js';
 export { createMachineRunsClient } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan, } from './executor.js';
 export { createNodeAutomationProcessHost, } from './node-process-host.js';

package/dist/src/machine-client.d.ts

@@ -5,4 +5,6 @@ export declare function createMachineRunsClient(options: {
     readonly headers: AutomationRequestHeaders;
     readonly fetch?: typeof globalThis.fetch;
     readonly requestTimeoutMs?: number;
-}): MachineRuns;
+}): MachineRuns & {
+    notifications(signal: AbortSignal): AsyncIterable<void>;
+};

package/dist/src/machine-client.js

@@ -1,4 +1,5 @@
 import { AutomationError } from './errors.js';
+import { machineEventStream } from './machine-event-stream.js';
 export function createMachineRunsClient(options) {
     const baseUrl = options.baseUrl.replace(/\/$/, '');
     const fetch = options.fetch ?? globalThis.fetch;
@@ -23,6 +24,11 @@ export function createMachineRunsClient(options) {
         return payload;
     };
     return Object.freeze({
+        notifications(signal) {
+            return machineEventStream({
+                url: `${baseUrl}/v1/machine/runs/notifications`, headers: options.headers, fetch, signal,
+            });
+        },
         async claim(input = {}) {
             const result = await request('/v1/machine/runs/claim', 'POST', input);
             return result.runs;

package/dist/src/machine-event-stream.d.ts

@@ -0,0 +1,8 @@
+import type { AutomationRequestHeaders } from './machine-client.js';
+/** A wakeup stream carries no run data; every reconnect gets fresh authorization. */
+export declare function machineEventStream(options: {
+    readonly url: string;
+    readonly headers: AutomationRequestHeaders;
+    readonly fetch: typeof globalThis.fetch;
+    readonly signal: AbortSignal;
+}): AsyncGenerator<void>;

package/dist/src/machine-event-stream.js

@@ -0,0 +1,58 @@
+import { AutomationError } from './errors.js';
+/** A wakeup stream carries no run data; every reconnect gets fresh authorization. */
+export async function* machineEventStream(options) {
+    const connection = new AbortController();
+    const signal = AbortSignal.any([options.signal, connection.signal]);
+    let rejectAborted;
+    const aborted = new Promise((_, reject) => { rejectAborted = reject; });
+    const abort = () => rejectAborted(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    let timeout = setTimeout(() => connection.abort(new Error('Notification connection timed out')), 15_000);
+    timeout.unref();
+    let reader;
+    try {
+        const headers = await Promise.race([
+            Promise.resolve().then(() => { signal.throwIfAborted(); return options.headers('GET', options.url); }),
+            aborted,
+        ]);
+        signal.throwIfAborted();
+        const response = await options.fetch(options.url, {
+            headers: { ...headers, accept: 'text/event-stream' }, signal,
+        });
+        if (!response.ok)
+            throw new AutomationError('notifications_unavailable', `Automations notifications returned ${response.status}`, response.status);
+        if (!response.headers.get('content-type')?.startsWith('text/event-stream') || !response.body) {
+            throw new Error('Expected an Automations notification stream');
+        }
+        reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let pending = '';
+        while (!signal.aborted) {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => connection.abort(new Error('Notification connection went silent')), 75_000);
+            timeout.unref();
+            const { value, done } = await reader.read();
+            if (done)
+                throw new Error('Automations notification connection closed');
+            pending += decoder.decode(value, { stream: true });
+            let boundary;
+            while ((boundary = /\r?\n\r?\n/.exec(pending))) {
+                const frame = pending.slice(0, boundary.index);
+                pending = pending.slice(boundary.index + boundary[0].length);
+                if (frame.length > 16_384)
+                    throw new Error('Automations notification is too large');
+                if (/^event: ?(?:ready|wake)\r?$/m.test(frame))
+                    yield;
+            }
+            if (pending.length > 16_384)
+                throw new Error('Automations notification is too large');
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        signal.removeEventListener('abort', abort);
+        connection.abort();
+        await reader?.cancel().catch(() => { });
+        reader?.releaseLock();
+    }
+}

package/dist/src/machine-http.d.ts

@@ -1,5 +1,7 @@
 import type { AutomationMachinePrincipal, MachineRuns } from './machine.js';
+import type { MachineRunNotifications } from './machine-notifications.js';
 export declare function createMachineRunsApi(options: {
     readonly authenticate: (request: Request) => Promise<AutomationMachinePrincipal>;
     readonly runsFor: (principal: AutomationMachinePrincipal) => MachineRuns;
+    readonly notifications?: Pick<MachineRunNotifications, 'open'>;
 }): (request: Request) => Promise<Response>;

package/dist/src/machine-http.js

@@ -7,7 +7,13 @@ export function createMachineRunsApi(options) {
             if (parts[0] !== 'v1' || parts[1] !== 'machine' || parts[2] !== 'runs') {
                 return json(404, { error: 'Not found' });
             }
-            const runs = options.runsFor(await options.authenticate(request));
+            const principal = await options.authenticate(request);
+            if (parts[3] === 'notifications' && parts.length === 4 && request.method === 'GET') {
+                if (!options.notifications)
+                    throw new AutomationError('unavailable', 'Notifications unavailable', 503);
+                return options.notifications.open(principal, request.signal);
+            }
+            const runs = options.runsFor(principal);
             if (parts[3] === 'claim' && parts.length === 4 && request.method === 'POST') {
                 return json(200, { runs: await runs.claim(await body(request)) });
             }
@@ -18,7 +24,7 @@ export function createMachineRunsApi(options) {
         }
         catch (error) {
             if (error instanceof AutomationError)
-                return json(error.code === 'validation' ? 400 : 403, {
+                return json(error.status ?? (error.code === 'validation' ? 400 : 403), {
                     error: error.message, code: error.code,
                 });
             const code = error instanceof Error && 'code' in error ? String(error.code) : 'internal';

package/dist/src/machine-notifications.d.ts

@@ -0,0 +1,15 @@
+import type { AutomationMachinePrincipal } from './machine.js';
+/** Ephemeral wakeups only. Supabase remains the queue and the eligibility clock. */
+export declare function createMachineRunNotifications(options: {
+    readonly wakeDelay: (userId: string, computerId: string) => Promise<number | null>;
+    readonly heartbeatMs?: number;
+    readonly maxStreamMs?: number;
+    readonly log?: (event: string, details: Readonly<Record<string, unknown>>) => void;
+}): Readonly<{
+    connected(): void;
+    disconnected: () => void;
+    close: () => void;
+    changed(userId: string, computerId: string): void;
+    open(principal: AutomationMachinePrincipal, signal: AbortSignal): Response;
+}>;
+export type MachineRunNotifications = ReturnType<typeof createMachineRunNotifications>;

package/dist/src/machine-notifications.js

@@ -0,0 +1,124 @@
+import { AutomationError } from './errors.js';
+/** Ephemeral wakeups only. Supabase remains the queue and the eligibility clock. */
+export function createMachineRunNotifications(options) {
+    const targets = new Map();
+    const encoder = new TextEncoder();
+    let connected = false;
+    const key = (userId, computerId) => JSON.stringify([userId, computerId]);
+    const refresh = async (target) => {
+        target.dirty = true;
+        if (target.refreshing)
+            return;
+        target.refreshing = true;
+        try {
+            while (target.dirty && target.listeners.size) {
+                target.dirty = false;
+                clearTimeout(target.timer);
+                const delay = await options.wakeDelay(target.userId, target.computerId);
+                if (target.dirty || !target.listeners.size)
+                    continue;
+                if (delay === null)
+                    continue;
+                if (!Number.isFinite(delay) || delay < 0)
+                    throw new Error('Invalid machine wake delay');
+                if (delay === 0) {
+                    for (const listener of target.listeners)
+                        listener.send('wake');
+                }
+                else {
+                    target.timer = setTimeout(() => void refresh(target), Math.min(delay, 2_147_483_647));
+                    target.timer.unref();
+                }
+            }
+        }
+        catch {
+            options.log?.('automations.notifications.failed', { boundary: 'wake-deadline' });
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+        finally {
+            target.refreshing = false;
+        }
+    };
+    const disconnect = () => {
+        connected = false;
+        for (const target of targets.values()) {
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+    };
+    return Object.freeze({
+        connected() { connected = true; },
+        disconnected: disconnect,
+        close: disconnect,
+        changed(userId, computerId) {
+            const target = targets.get(key(userId, computerId));
+            if (target)
+                void refresh(target);
+        },
+        open(principal, signal) {
+            if (!connected)
+                throw new AutomationError('unavailable', 'Notifications are reconnecting', 503);
+            signal.throwIfAborted();
+            const targetKey = key(principal.userId, principal.computerId);
+            let target = targets.get(targetKey);
+            if (!target) {
+                target = { ...principal, listeners: new Set(), refreshing: false, dirty: false };
+                targets.set(targetKey, target);
+            }
+            const current = target;
+            let close = (_closeStream = true) => { };
+            const body = new ReadableStream({
+                start(controller) {
+                    let closed = false;
+                    let heartbeat;
+                    let expiry;
+                    const abort = () => close();
+                    close = (closeStream = true) => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        clearInterval(heartbeat);
+                        clearTimeout(expiry);
+                        signal.removeEventListener('abort', abort);
+                        current.listeners.delete(listener);
+                        if (!current.listeners.size) {
+                            clearTimeout(current.timer);
+                            targets.delete(targetKey);
+                        }
+                        if (closeStream)
+                            controller.close();
+                    };
+                    const listener = {
+                        send(event) {
+                            if (closed)
+                                return;
+                            if ((controller.desiredSize ?? 0) <= 0)
+                                return close();
+                            controller.enqueue(encoder.encode(event === 'heartbeat'
+                                ? ': keepalive\n\n' : `event: ${event}\ndata: {}\n\n`));
+                        },
+                        close,
+                    };
+                    current.listeners.add(listener);
+                    signal.addEventListener('abort', abort, { once: true });
+                    heartbeat = setInterval(() => listener.send('heartbeat'), options.heartbeatMs ?? 30_000);
+                    heartbeat.unref();
+                    const lifetime = Math.min(options.maxStreamMs ?? 300_000, (principal.authorizationExpiresAt ?? Infinity) - Date.now());
+                    expiry = setTimeout(close, Math.max(0, lifetime));
+                    expiry.unref();
+                    listener.send('ready');
+                    void refresh(current);
+                },
+                cancel() { close(false); },
+            }, { highWaterMark: 8 });
+            return new Response(body, {
+                headers: {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-store, no-transform',
+                    'x-accel-buffering': 'no',
+                },
+            });
+        },
+    });
+}

package/dist/src/machine.d.ts

@@ -4,6 +4,7 @@ export interface AutomationMachinePrincipal {
     readonly userId: string;
     readonly computerId: string;
     readonly scopes: readonly AutomationScope[];
+    readonly authorizationExpiresAt?: number;
 }
 export interface ClaimedAutomationRun extends AutomationRun {
     readonly leaseToken: string;

package/dist/src/runner.d.ts

@@ -1,13 +1,15 @@
 import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
 export interface AutomationMachineRunnerOptions {
     readonly runs: MachineRuns;
+    readonly notifications: (signal: AbortSignal) => AsyncIterable<void>;
     readonly execute: (run: ClaimedAutomationRun) => Promise<void>;
     readonly batchSize?: number;
     readonly leaseSeconds?: number;
-    readonly pollIntervalMs?: number;
+    readonly reconnectDelayMs?: number;
     readonly maxBackoffMs?: number;
     readonly log?: (event: string, details?: Readonly<Record<string, unknown>>) => void;
 }
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export declare function createAutomationMachineRunner(options: AutomationMachineRunnerOptions): Readonly<{
     start(): void;
     close(): Promise<void>;

package/dist/src/runner.js

@@ -1,61 +1,84 @@
+import { setTimeout as delay } from 'node:timers/promises';
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export function createAutomationMachineRunner(options) {
     const batchSize = integer(options.batchSize ?? 8, 1, 20, 'batchSize');
     const leaseSeconds = integer(options.leaseSeconds ?? 60, 30, 900, 'leaseSeconds');
-    const pollIntervalMs = integer(options.pollIntervalMs ?? 1_000, 1, 60_000, 'pollIntervalMs');
-    const maxBackoffMs = integer(options.maxBackoffMs ?? Math.max(30_000, pollIntervalMs), pollIntervalMs, 300_000, 'maxBackoffMs');
-    let active = null;
-    let timer = null;
-    let stopped = true;
-    let failures = 0;
-    let nextDelay = pollIntervalMs;
-    const schedule = (delay) => {
-        if (stopped)
+    const reconnectDelayMs = integer(options.reconnectDelayMs ?? 1_000, 1, 60_000, 'reconnectDelayMs');
+    const maxBackoffMs = integer(options.maxBackoffMs ?? 30_000, reconnectDelayMs, 300_000, 'maxBackoffMs');
+    let lifetime = null;
+    let listening = null;
+    let draining = null;
+    let pending = false;
+    const wake = (connection, signal) => {
+        pending = true;
+        if (draining)
             return;
-        timer = setTimeout(drain, delay);
-        timer.unref?.();
-    };
-    const drain = () => {
-        if (stopped || active)
-            return active;
-        active = options.runs.claim({ limit: batchSize, leaseSeconds })
-            .then(async (runs) => {
-            failures = 0;
-            if (runs.length)
-                options.log?.('automations.claimed', { count: runs.length });
-            const settled = await Promise.allSettled(runs.map(options.execute));
-            settled.forEach((result) => {
-                if (result.status === 'rejected') {
-                    options.log?.('automations.run.failed', { error: safe(result.reason) });
+        draining = (async () => {
+            while (pending && !signal.aborted) {
+                pending = false;
+                const runs = await options.runs.claim({ limit: batchSize, leaseSeconds });
+                if (runs.length)
+                    options.log?.('automations.claimed', { count: runs.length });
+                const settled = await Promise.allSettled(runs.map(options.execute));
+                for (const result of settled) {
+                    if (result.status === 'rejected')
+                        options.log?.('automations.run.failed', { error: safe(result.reason) });
                 }
-            });
-            nextDelay = runs.length === batchSize ? 0 : pollIntervalMs;
-        })
-            .catch((error) => {
-            failures += 1;
-            const delayMs = Math.min(maxBackoffMs, pollIntervalMs * (2 ** Math.min(failures - 1, 10)));
-            options.log?.('automations.poll.failed', { error: safe(error), retryInMs: delayMs });
-            nextDelay = delayMs;
-        })
-            .finally(() => {
-            active = null;
-            schedule(nextDelay);
+                // Work may arrive while execution is busy, including a partial last batch.
+                pending ||= runs.length > 0;
+            }
+        })().catch((error) => {
+            options.log?.('automations.claim.failed', { error: safe(error) });
+            connection.abort(error);
+        }).finally(() => {
+            draining = null;
+            if (pending && !signal.aborted && !connection.signal.aborted)
+                wake(connection, signal);
         });
-        return active;
+    };
+    const listen = async (signal) => {
+        let failures = 0;
+        while (!signal.aborted) {
+            const connection = new AbortController();
+            const connectedSignal = AbortSignal.any([signal, connection.signal]);
+            const startedAt = Date.now();
+            try {
+                for await (const _ of options.notifications(connectedSignal)) {
+                    if (connectedSignal.aborted)
+                        break;
+                    wake(connection, signal);
+                }
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    options.log?.('automations.notifications.disconnected', { error: safe(error) });
+            }
+            finally {
+                connection.abort();
+                await draining;
+            }
+            if (signal.aborted)
+                break;
+            // A flapping stream must not reset its backoff merely by sending ready.
+            failures = Date.now() - startedAt >= 30_000 ? 0 : failures + 1;
+            const backoff = Math.min(maxBackoffMs, reconnectDelayMs * 2 ** Math.min(Math.max(0, failures - 1), 10));
+            await delay(backoff, undefined, { signal, ref: false }).catch(() => { });
+        }
     };
     return Object.freeze({
         start() {
-            if (!stopped)
+            if (lifetime)
                 return;
-            stopped = false;
-            failures = 0;
-            void drain();
+            lifetime = new AbortController();
+            pending = false;
+            listening = listen(lifetime.signal);
         },
         async close() {
-            stopped = true;
-            if (timer)
-                clearTimeout(timer);
-            timer = null;
-            await active;
+            lifetime?.abort();
+            await listening;
+            await draining;
+            lifetime = null;
+            listening = null;
         },
     });
 }

package/dist/src/supabase-machine.d.ts

@@ -11,6 +11,7 @@ export declare class SupabaseMachineRunRepository implements MachineRunRepositor
     #private;
     private readonly client;
     constructor(client: MachineRpcClient);
+    wakeDelay(userId: string, computerId: string): Promise<number | null>;
     claim(input: Parameters<MachineRunRepository['claim']>[0]): Promise<ClaimedAutomationRun[]>;
     update(input: Parameters<MachineRunRepository['update']>[0]): Promise<ClaimedAutomationRun | null>;
 }

package/dist/src/supabase-machine.js

@@ -4,6 +4,9 @@ export class SupabaseMachineRunRepository {
     constructor(client) {
         this.client = client;
     }
+    wakeDelay(userId, computerId) {
+        return this.#call('amalgm_machine_wake_delay', { p_user_id: userId, p_target_id: computerId });
+    }
     async claim(input) {
         const rows = await this.#call('claim_amalgm_machine_runs', {
             p_user_id: input.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
@@ -49,6 +49,7 @@
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:supabase": "tsx --test test/integration/postgres.test.ts",
+    "test:notifications": "tsx scripts/test-notifications.ts",
     "verify": "npm run check && npm test && npm run build && tsx scripts/check-cli-artifact.ts",
     "release:check": "npm run verify && npm run test:supabase",
     "prepack": "npm run build",

package/skills/amalgm-automations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amalgm-automations
-description: Operate complete Amalgm automations through the Automations MCP tools or the global `amalgm automations` CLI, including schedules, webhooks, Run Now, run history, native commands, scripts, and Amalgm actions.
+description: Set up, operate, and troubleshoot Amalgm Automations through MCP or the amalgm automations CLI. Use for installation, Google sign-in, scheduled or webhook workflows, Run Now, run history, and Automations support.
 ---
 
 # Amalgm Automations
@@ -10,6 +10,10 @@ workflow into one durable Amalgm automation and verify what actually ran.
 Automations owns configuration and permanent run history; the selected Amalgm
 machine executes the workflow.
 
+Amalgm Automations is free. Guide the person through Google sign-in and computer
+approval when needed; do not introduce a payment step. A native agent or other
+external service still uses its own account and may have its own usage costs.
+
 ## Choose the available adapter
 
 Prefer the six `amalgm_automations_*` MCP tools when they are callable. In a
@@ -28,11 +32,22 @@ amalgm_automations_run_now          amalgm automations run-now
 Both adapters accept the same JSON object and call the same SDK command
 surface. Do not translate one into a different resource-level API.
 
-For CLI use, first check `amalgm automations --help`. A signed-in, running
-Amalgm Shell supplies authentication through its loopback runtime. Never ask
-the user to copy a runtime token, DPoP proof, device key, or machine credential.
-If the runtime is unavailable, report that Shell must be signed in and running;
-do not fall back to an invented credential flow.
+Reuse a working connection. For an available MCP connection, a small `list`
+request with `{"limit":1}` proves access; do not install or log in again. For
+CLI use, check `amalgm automations --help` and use
+`amalgm automations list --input '{"limit":1}'`. An empty successful list is
+ready, not a setup failure. Respect an explicitly selected account.
+
+If the user asks to install or sign in, or that read fails, read
+[setup and support](references/setup-and-support.md). It covers the supported
+install, browser approval, account selection, runtime restart, and recovery
+commands. Carry setup through to a successful Automations read, then resume
+the original request. Do not stop at “Shell must be running.”
+
+Shell owns authentication. Never read, copy, or ask the user to supply a runtime
+token, DPoP proof, device key, or machine credential. The public connection
+commands obtain what they need; environment-variable credential setup is not
+the user login flow.
 
 Read [references/command-contract.md](references/command-contract.md) whenever
 composing `create` or `update`, or when exact fields are uncertain. Read
@@ -92,22 +107,42 @@ not evidence that work completed.
    returned run id must remain the same.
 3. Poll `get` with `include_runs: true` or a `run_query` until the admitted run
    becomes `completed` or `failed`. Match the exact run id; do not assume the
-   newest unrelated run is yours.
+   newest unrelated run is yours. Space out reads and back off while state is
+   unchanged; a rate-limit response is a reason to wait, not to submit again.
 4. Inspect every step's status and bounded output. Report failure honestly,
    including the failing step and service error.
 
 `pending` means durable and awaiting its machine. `sent` or `running` means the
 machine holds a lease. Only `completed` and `failed` are terminal.
 
+Keep the user informed while waiting. If the machine stays unavailable or the
+current session cannot keep waiting, report the exact run id and observed
+nonterminal state; do not claim completion, create a replacement, or promise
+background monitoring that has not been set up.
+
 Diagnose at the failing boundary. Examples: `process_execution_unavailable`
 means that machine lacks the process host; an executable-not-found error is a
 machine PATH/install problem; `Installed agent has no model` is agent
 configuration; an action-specific HTTP error belongs to that action service.
 Do not relabel these as Run Now failures or patch the automation around them.
 
+## Help when something goes wrong
+
+Use [setup and support](references/setup-and-support.md) for login/runtime
+failures, HTTP 429 or reported rate limits, and contacting support. Preserve
+the actual error code, distinguish the failing service, and use bounded retries.
+Do not invent minute/hour allowances or reset times that the service has not
+reported.
+
+For an unresolved issue, offer **Email Aayush at aayush@amalgm.ai** and prepare
+a concise, redacted draft when helpful. Send only with the user's explicit
+authorization and an available email tool; otherwise give them the draft.
+
 ## Report the outcome
 
 Return the automation id, target choice if the user selected one, trigger
 summary, workflow lanes, and—when execution was requested—the exact run id and
 terminal result. Mention that run history is durable. Never claim a schedule
 fired merely because configuration creation succeeded.
+Include automation/run links when returned by the product; do not invent a
+deep link or use a private webhook URL as a viewing link.

package/skills/amalgm-automations/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Amalgm Automations"
-  short_description: "Create and verify durable Amalgm automations"
-  default_prompt: "Use $amalgm-automations to create and verify an automation for me."
+  short_description: "Set up, run, and troubleshoot Amalgm automations"
+  default_prompt: "Use $amalgm-automations to help me connect my account and create and verify an automation."

package/skills/amalgm-automations/references/setup-and-support.md

@@ -0,0 +1,195 @@
+# Setup and support
+
+Read this when installing, signing in, repairing a connection, or helping with
+an error. Use Shell's commands for setup and Automations reads to verify access.
+The agent handles the commands; the person chooses their Google account and
+approves connecting their computer in the browser.
+
+## Start with the connection you have
+
+If Automations MCP already answers `list` with `{"limit":1}`, continue the task.
+Do not require a local CLI for a working remote MCP connection. If that remote
+connection requires authorization, use its actual sign-in/reconnect link. A
+cloud agent cannot repair the user's computer by installing Shell on its own
+temporary machine.
+
+For local CLI work, use the existing `amalgm` executable or the exact Shell
+launcher supplied by Amalgm's installer/app. The examples below use `amalgm`
+as shorthand for that executable. Keep the same installation and account
+throughout setup and verification.
+
+```bash
+amalgm --version
+amalgm --help
+amalgm automations --help
+amalgm automations list --input '{"limit":1}'
+```
+
+When the user has chosen an account, add `--user` with that actual email to
+Shell commands, including `amalgm automations ...`. An email selects a local
+account; it does not authenticate it. `targetId` selects an execution computer,
+not an account. Never substitute one for the other.
+
+A successful Automations response is a JSON `result` envelope; an empty list
+is valid. The six Automations commands use that envelope. Shell's `status`
+returns a different JSON shape; `login` and `run` report progress as text.
+
+## Install only when needed
+
+Check for an existing app-managed installation before adding another copy.
+If the desktop app already manages this computer, use its setup/connection
+flow. A missing PATH entry is not proof that Amalgm is uninstalled.
+
+On a fresh computer with Node.js and npm, the Shell package supplies the
+global command. Check the published package's requirements before installing:
+
+```bash
+node --version
+npm view @amalgm/shell version engines --json
+npm install --global @amalgm/shell
+amalgm --version
+amalgm automations --help
+```
+
+Do not install `@amalgm/automations` alone as a substitute for Shell: its direct
+CLI/MCP executables do not perform the user's Shell login. Do not change an
+existing app's exact runtime binding or install a second runner to fix a
+version mismatch. If the installed Shell lacks `automations`, report that
+version and use its supported update path; do not invent `amalgm update`.
+
+If Node/npm is unavailable or global installation is denied, use
+[Amalgm computer setup](https://amalgm.ai/setup). The person signs in with
+Google and the page supplies the current platform-specific install command.
+That installer includes a private Node runtime and a one-time setup code.
+Execute the command supplied by the trusted setup page when the user has
+authorized connecting this computer. Do not invent a code, run a code-less
+`install.sh`, or use sudo as an automatic workaround. Keep the code private
+to this setup session.
+
+The web installer places Shell under
+`~/.amalgm/runtime-packages/shell/<installed-version>/bin/amalgm` on macOS/Linux.
+If it is absent from PATH, use the exact launcher/version identified by the
+installer or app, not whichever version directory happens to sort last.
+
+## Sign in and connect the computer
+
+For a first login through the CLI:
+
+```bash
+amalgm login --no-open
+```
+
+Run it in a persistent terminal/process session. Show the **verification URL
+printed by that process** to the user as a clickable link; do not construct
+the URL yourself. Omit `--no-open` only when the command should open the browser
+on the same computer. The approval link and setup code are short-lived setup
+information, not material for logs or support emails.
+
+Tell the person: “Continue with Google, choose your Amalgm account, and approve
+connecting this computer. I'll check the connection and continue afterward.”
+Show the computer name when known. The browser owns sign-in and consent; do
+not ask for passwords, provider tokens, or a credit card. Existing accounts
+can use their existing supported sign-in method rather than creating a second
+account just to use Google.
+
+Keep that process alive while the person approves. Follow its progress until
+`AMALGM_READY` appears or it reports an error. `login` continues hosting the
+runtime after readiness; it is not expected to exit successfully. Do not kill
+it after approval or use `--exit-after-ready` for real setup.
+
+An already approved, unexpired code can be passed to
+`amalgm login --setup-code CODE` if the original waiting process ended. Use
+only the actual code from this setup attempt. If approval expired, finish the
+old attempt and start a fresh login. If the person cancels, stop that attempt;
+do not reopen approval until they choose to continue.
+
+## Reuse or resume a registered computer
+
+Once the account email is known, inspect it explicitly. Replace the example
+email below with the user's actual selected account:
+
+```bash
+amalgm status --user person@example.com
+```
+
+| Observed state | Next action |
+| --- | --- |
+| `registration: "ready"`, `running: true` | Reuse this runtime; verify Automations access. |
+| `registration: "ready"`, `running: false` | Run `amalgm run --user person@example.com` in a persistent session, then verify. |
+| `registration: "absent"` or `"incomplete"` | Complete the supported login/setup flow for this account; preserve existing registration files. |
+| Shell requests `--user` or lists several accounts | Ask which account to use if it is not already established. Supply that email consistently. |
+| Status fails | Diagnose the actual error; a failed read is not proof that registration is absent. |
+
+After login or resume, require both ready/running status and a successful read:
+
+```bash
+amalgm automations list --user person@example.com --input '{"limit":1}'
+```
+
+Then return to the user's original automation request. This proves connection
+and access, not that a future workflow ran or that every executable is installed.
+MCP results can independently prove hosted access, but do not prove the selected
+execution computer is online.
+
+Use an existing app/installer-managed background runtime when possible. A
+foreground `login`/`run` process must remain alive for local execution; do not
+promise it survives terminal closure, logout, or reboot without evidence. If
+the agent's process sessions cannot persist, use the app/setup-managed path or
+explain the remaining requirement. An offline target leaves admitted runs
+pending; it does not erase their history.
+
+## Diagnose the failing boundary
+
+Read the error's code, message, and status together; some Shell failures are
+wrapped as `internal`. Keep automation and run ids when available. Try the
+appropriate repair and verify again. If the same failure persists with no new
+evidence, explain it and offer support rather than looping through login,
+reinstallation, or repeated writes.
+
+| Failure | What to do |
+| --- | --- |
+| `runtime_unavailable`, connection refused, or Shell says it is not running | Inspect the selected account's status and use the resume/setup decision above. A standalone adapter asking for environment credentials should be replaced by the global `amalgm automations` path. |
+| `runtime_unauthorized` | Retry the read once through the public Shell command, which obtains the current local connection. If it still fails, keep the error for support; never extract or replace tokens manually. |
+| `runtime_transport` or `runtime_protocol` | Check local readiness, connectivity, and the installed version. A timeout or service outage is not evidence that the user needs a new account. |
+| Wrong account, `forbidden`, or a target authorization error | Verify the chosen account and computer. Do not change ownership, guess another target, or treat every 403 as an expired login. |
+| Missing/corrupt device key or an explicit recovery-required error | Explain key recovery and use `amalgm auth recover --user person@example.com` only when the user chooses recovery. It requires its own browser approval. Never delete identity files or silently re-register. After recovery, inspect status and resume if needed. |
+| HTTP 429 or a reported rate limit | Honor a supplied retry delay/reset time and reduce request frequency. Limits are per minute/hour; do not invent numeric allowances or a reset time. If no delay is supplied, back off conservatively with a bounded retry, then report the unresolved limit. Never switch accounts to bypass it. |
+| An installed native agent needs login, or its model/provider rejects work | Use that program/service's own supported login. Amalgm Google sign-in does not sign into Codex, Claude, or other providers. Do not add Amalgm credits as a guessed fix. |
+| Missing executable, failed step, or invalid workflow | Read [workflow diagnoses](workflow-plans.md#common-boundary-diagnoses); repair the actual step/configuration without replacing the automation to hide the failure. |
+
+For a failed mutation, inspect existing state before retrying. Reuse the same
+Run Now input and idempotency key after an uncertain response. Preserve a
+returned disabled draft id. A retry must not turn one requested automation or
+run into several.
+
+## Get support
+
+Support is **Aayush, aayush@amalgm.ai**:
+[Email Aayush](mailto:aayush@amalgm.ai?subject=Amalgm%20Automations%20help).
+Offer this as soon as the user asks, or when the supported repair does not
+resolve their problem. They do not need to complete a troubleshooting checklist
+to contact a person.
+
+Prepare a short email when helpful:
+
+```text
+To: aayush@amalgm.ai
+Subject: Amalgm Automations — <short problem>
+
+I was trying to: <intended result>
+What happened: <failure and approximate time, including timezone>
+Setup: <OS, agent/client, and Amalgm version if available>
+Error: <code/status and a short redacted message>
+Automation/run: <ids or viewing links, if available>
+Already tried: <relevant checks or repair>
+```
+
+Use only relevant evidence. Do not attach raw runtime logs, browser cookies,
+private auth files, setup links/codes, webhook URLs/signing secrets, or the
+user's code, prompts, file paths, and workflow output without reviewing and
+redacting them. Status output can contain private local paths; summarize its
+registration/running fields instead of copying the entire object.
+
+Send through an available email tool only if the user has explicitly authorized
+the email; otherwise provide the draft and mail link. Do not invent a support
+ticket, response-time promise, or claim that an email was sent.

package/supabase/migrations/20260904020000_machine_run_notifications.sql

@@ -0,0 +1,52 @@
+-- Commit the run and its private wakeup together. Every Fly host observes the
+-- same change; local processes never subscribe with Supabase credentials.
+CREATE OR REPLACE FUNCTION public.notify_amalgm_machine_run()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+BEGIN
+  IF TG_OP = 'UPDATE' AND
+    (OLD.status, OLD.retry_at, OLD.lease_expires_at) IS NOT DISTINCT FROM
+    (NEW.status, NEW.retry_at, NEW.lease_expires_at) THEN
+    RETURN NEW;
+  END IF;
+  PERFORM realtime.send(
+    jsonb_build_object('userId', NEW.user_id, 'targetId', NEW.target_id),
+    'changed', 'amalgm:automations:runs', true
+  );
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.notify_amalgm_machine_run() FROM PUBLIC;
+CREATE TRIGGER amalgm_machine_run_notification
+AFTER INSERT OR UPDATE ON public.amalgm_automation_runs
+FOR EACH ROW EXECUTE FUNCTION public.notify_amalgm_machine_run();
+
+-- Remain private even if a different product permits broad authenticated
+-- Broadcast access. service_role is the only subscriber and bypasses RLS.
+CREATE POLICY amalgm_run_notifications_service_only
+ON realtime.messages AS RESTRICTIVE FOR ALL TO PUBLIC
+USING (topic <> 'amalgm:automations:runs')
+WITH CHECK (topic <> 'amalgm:automations:runs');
+
+-- Use the database clock, exactly as claim_amalgm_machine_runs does. The host
+-- sleeps until this deadline; no deadline means no work-check timer at all.
+CREATE OR REPLACE FUNCTION public.amalgm_machine_wake_delay(p_user_id uuid, p_target_id text)
+RETURNS double precision
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT CASE WHEN count(*) = 0 THEN NULL ELSE
+    greatest(0, ceil(extract(epoch FROM (min(CASE WHEN status = 'pending'
+      THEN coalesce(retry_at, now()) ELSE coalesce(lease_expires_at, now()) END) - now())) * 1000))
+  END
+  FROM public.amalgm_automation_runs
+  WHERE user_id = p_user_id AND target_id = p_target_id
+    AND status IN ('pending', 'sent', 'running');
+$$;
+REVOKE ALL ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) TO service_role;

package/supabase/migrations/20260904030000_machine_notification_permissions.sql

@@ -0,0 +1,4 @@
+-- Supabase can grant EXECUTE directly through schema default privileges;
+-- revoking PUBLIC alone does not remove those explicit grants.
+REVOKE ALL ON FUNCTION public.notify_amalgm_machine_run() FROM anon, authenticated;
+REVOKE ALL ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) FROM anon, authenticated;