@attocash/cli 0.1.2 → 0.2.0

package/README.md

@@ -689,6 +689,45 @@ mnemonic is lost from the password store, recover it from your private backup
 using `atto wallet import` in an uninitialized profile. Preserve the old public
 state and pending-send records for reconciliation before resuming payments.
 
+## Background receiving and work preparation
+
+`atto wallet receive` keeps automatic receiving in the current terminal. To
+keep receiving after the terminal exits, use:
+
+```sh
+atto wallet receive --background
+atto wallet receive status
+atto wallet receive stop
+```
+
+The background receiver uses the same profile selected by `--data-dir`, the OS
+password store, active addresses, minimum receive amount, and automatic
+receiving setting. It does not install a service, does not start after reboot,
+and does not grant MCP spending access. `wallet status` reports its separate
+state and latest operational error. Stop it before resetting a profile.
+
+All three commands accept `--data-dir <directory>` and `--json`. Starting or
+stopping repeatedly is safe. Start acknowledges local initialization; it does
+not promise that the node or password store is reachable. The detached process
+inherits your login environment and needs access to the OS password store. On
+Linux, keep the Secret Service session available; on macOS and Windows, allow
+the CLI to access its credential. Check `wallet receive status` for retry errors.
+No recovery phrase is stored in the public profile or passed on the command line.
+
+Stop prevents new receives and reports `stopping` until the current operation
+finishes. A crashed receiver reports `stopped`; start it explicitly again after
+a crash, reboot, or restoring a backup. Foreground and MCP receivers may coexist,
+but stopping this background receiver does not stop those separate sessions.
+
+After a completed send, receive, representative change, or approved pool step,
+the CLI may finish public proof-of-work preparation in a short detached process.
+This contains only public account heads and worker settings, runs for at most a
+minute, and caches usable work for a later transaction. A changed account head
+or an immediate transaction can still require fresh work.
+The worker exits when its queue is drained, keeps at most two speculative
+requests active, and leaves failed or unfinished jobs eligible for a later CLI
+invocation. Reset cancels queued preparation before clearing the profile.
+
 ## Update notices
 
 Interactive CLI commands can show a notice on stderr when a newer stable CLI

package/dist/application/app.d.ts

@@ -4,6 +4,7 @@ import type { SendRetry } from '../network/retry.js';
 import { type SecretStore } from '../storage/secrets.js';
 import { StateStore } from '../storage/state.js';
 import { SpendLedger, type McpAccess } from '../spending/ledger.js';
+import { type WorkExecution } from '../wallet/work.js';
 import { type ReceiveProgress } from '../wallet/auto-receive.js';
 import type { AccountPool, SpendingPolicy, WalletIdentity } from '../wallet/types.js';
 import { MarketData } from '../pricing/market.js';
@@ -16,6 +17,10 @@ export declare class AttoApplication {
     private readonly labels;
     private readonly auto;
     private readonly work;
+    private readonly background;
+    private readonly receivingAllowed;
+    private preparation?;
+    private readonly preparationAbort;
     private readonly payments;
     private watchManager?;
     private watchConfiguration;
@@ -36,6 +41,8 @@ export declare class AttoApplication {
         sendRetry?: SendRetry;
         globalDirectory?: GlobalDirectory;
         onDestination?: (binding: DestinationBinding) => void;
+        workExecution?: WorkExecution;
+        receivingAllowed?: () => boolean;
     });
     private settings;
     private addresses;
@@ -133,6 +140,10 @@ export declare class AttoApplication {
     private invoke;
     call(name: string, input?: Record<string, unknown>): Promise<unknown>;
     start(): Promise<void>;
+    /** Terminal-only detached receiver control; it never changes MCP approval. */
+    startBackgroundReceiver(): Promise<import("../wallet/background-receive.js").BackgroundReceiveStatus>;
+    stopBackgroundReceiver(): Promise<import("../wallet/background-receive.js").BackgroundReceiveStatus>;
+    resumeWork(): void;
     private preparePoolWork;
     close(): Promise<void>;
 }

package/dist/application/app.js

@@ -12,6 +12,7 @@ import { resolveWalletProfile } from '../storage/profiles.js';
 import { SpendLedger } from '../spending/ledger.js';
 import { Payments } from '../spending/payments.js';
 import { WalletWork } from '../wallet/work.js';
+import { BackgroundReceiver } from '../wallet/background-receive.js';
 import { WatchManager } from '../watches/manager.js';
 import { AutoReceiver } from '../wallet/auto-receive.js';
 import { defaultSettings } from '../wallet/defaults.js';
@@ -30,6 +31,10 @@ export class AttoApplication {
     labels;
     auto;
     work;
+    background;
+    receivingAllowed;
+    preparation;
+    preparationAbort = new AbortController();
     payments;
     watchManager;
     watchConfiguration = '';
@@ -55,13 +60,15 @@ export class AttoApplication {
                 if (!this.store.get('settings'))
                     this.store.set('settings', defaultSettings());
             });
-            this.work = new WalletWork(this.store, () => this.settings());
+            this.work = new WalletWork(this.store, () => this.settings(), options.workExecution);
+            this.background = new BackgroundReceiver(this.store);
+            this.receivingAllowed = options.receivingAllowed ?? (() => true);
             this.payments = new Payments(this.store, this.ledger, {
                 settings: () => this.settings(), addresses: () => this.addresses(), seed: () => this.seed(),
                 requireWrite: () => this.requireMcpWrite(), mcp: this.mcp,
             }, this.market, this.work, options.sendRetry, options.onDestination);
             this.auto = new AutoReceiver(() => ({
-                settings: this.mcp && this.ledger.mcpAccess() !== 'spend' ? { ...this.settings(), autoReceive: false } : this.settings(),
+                settings: !this.receivingAllowed() || (this.mcp && this.ledger.mcpAccess() !== 'spend') ? { ...this.settings(), autoReceive: false } : this.settings(),
                 addresses: this.addresses(),
             }), (index, hash) => this.receive({ index, hash }, true), event => options.onReceiveProgress?.(this.labels.decorate(event, this.settings().network)));
         }
@@ -178,6 +185,8 @@ export class AttoApplication {
         this.requireSession();
         if (this.mcp)
             throw new AttoError('LOCAL_APPROVAL_REQUIRED', 'Wallet reset requires approval in a local terminal.');
+        if (this.background.status().state !== 'stopped')
+            throw new AttoError('WALLET_BUSY', 'Stop the background receiver before resetting this wallet.');
         if (this.started || this.calls.size || this.recoveryReads || this.store.busy
             || this.watchManager?.list().some(watch => ['running', 'reconnecting'].includes(watch.status))) {
             throw new AttoError('WALLET_BUSY', 'Stop active wallet operations and reset from a new terminal command.');
@@ -202,7 +211,7 @@ export class AttoApplication {
         try {
             // A previous completed send may still have speculative public work queued.
             // Stop it before clearing state; normal calls cannot start during reset.
-            await this.work.close();
+            await this.work.cancel();
             await this.store.withExclusiveReset(() => this.store.withWalletLock(async () => {
                 if ((this.identity()?.fingerprint ?? null) !== expectedFingerprint) {
                     throw new AttoError('WALLET_CHANGED', 'The wallet changed after confirmation. Review it before resetting again.');
@@ -353,6 +362,8 @@ export class AttoApplication {
         return found;
     }
     async receive(request, automatic = false) {
+        if (automatic && !this.receivingAllowed())
+            throw new AttoError('AUTO_RECEIVE_DISABLED', 'Automatic receiving is stopping.');
         const index = request.index ?? 0;
         const operation = async () => {
             await this.store.withWalletLock(async () => {
@@ -374,6 +385,7 @@ export class AttoApplication {
                 if (transaction && transaction.hash.toString() === prior.blockHash && await transaction.isValid()) {
                     const result = this.result(transaction, 'received');
                     this.store.set(key, { ...prior, result });
+                    this.work.prepareConfirmed(transaction.block);
                     return result;
                 }
                 // Refresh pending state below: an unconsumed send permits retrying receive
@@ -403,9 +415,7 @@ export class AttoApplication {
                 const transaction = await wallet.receive(receivable, parseAddress(request.representative ?? this.settings().representative), null);
                 const result = { ...this.result(transaction, 'received'), index, amount: amountOutput(receivable.amount.toString()) };
                 this.store.set(key, { hash, index, blockHash: transaction.hash.toString(), result });
-                const account = await wallet.getAccountByIndex(toAttoIndex(index));
-                if (account)
-                    this.work.prepare([account]);
+                this.work.prepareConfirmed(transaction.block);
                 return result;
             }
             finally {
@@ -455,9 +465,7 @@ export class AttoApplication {
                 }, this.work.worker());
                 wallet = execution.wallet;
                 const transaction = await wallet.change(toAttoIndex(index), parseAddress(representative), null);
-                const account = await wallet.getAccountByIndex(toAttoIndex(index));
-                if (account)
-                    this.work.prepare([account]);
+                this.work.prepareConfirmed(transaction.block);
                 return this.result(transaction, 'representative_changed');
             }
             finally {
@@ -486,7 +494,7 @@ export class AttoApplication {
         const reader = this.reader();
         switch (name) {
             case 'doctor': return runDoctor({ directory: this.store.directory, access: this.mcp ? 'mcp' : undefined, signal: this.doctorAbort.signal, globalDirectory: args.globalDirectory });
-            case 'wallet_status': return { directory: this.store.directory, initialized: Boolean(this.identity()), identity: this.identity() ?? null, settings: this.settings(), addresses: this.addresses(), autoReceive: this.auto.status(), mcpAccess: this.ledger.mcpAccess(), pool: this.ledger.pool(), pendingSends: this.ledger.pending().map(({ id, hash, status }) => ({ requestId: id, hash, status })), resetPending: Boolean(this.store.get(RESET_KEY)) };
+            case 'wallet_status': return { directory: this.store.directory, initialized: Boolean(this.identity()), identity: this.identity() ?? null, settings: this.settings(), addresses: this.addresses(), autoReceive: this.auto.status(), backgroundReceive: this.background.status(), mcpAccess: this.ledger.mcpAccess(), pool: this.ledger.pool(), pendingSends: this.ledger.pending().map(({ id, hash, status }) => ({ requestId: id, hash, status })), resetPending: Boolean(this.store.get(RESET_KEY)) };
             case 'wallet_configure': return this.configure(args);
             case 'address_list': return { addresses: this.addresses() };
             case 'address_add': return this.store.withWalletLock(async () => {
@@ -628,14 +636,29 @@ export class AttoApplication {
         this.requireReady();
         this.started = true;
         this.auto.start();
-        await this.preparePoolWork();
+        this.preparation ??= this.preparePoolWork();
+        await this.preparation;
     }
+    /** Terminal-only detached receiver control; it never changes MCP approval. */
+    async startBackgroundReceiver() {
+        this.requireReady();
+        if (this.mcp)
+            throw new AttoError('LOCAL_APPROVAL_REQUIRED', 'Start background receiving through the CLI.');
+        return this.background.start();
+    }
+    async stopBackgroundReceiver() {
+        this.requireSession();
+        if (this.mcp)
+            throw new AttoError('LOCAL_APPROVAL_REQUIRED', 'Stop background receiving through the CLI.');
+        return this.background.stop();
+    }
+    resumeWork() { this.work.resume(); }
     async preparePoolWork() {
         if (this.mcp && this.ledger.mcpAccess() !== 'spend')
             return;
         const indexes = this.ledger.pool().indexes;
         await Promise.allSettled(this.addresses().filter(address => indexes.includes(address.index)).map(async (address) => {
-            const account = await this.reader().account(address.address);
+            const account = await this.reader().account(address.address, this.preparationAbort.signal);
             if (account && !this.closed)
                 this.work.prepare([account]);
         }));
@@ -645,7 +668,9 @@ export class AttoApplication {
             return;
         this.closed = true;
         this.doctorAbort.abort();
+        this.preparationAbort.abort();
         await this.auto.close();
+        await this.preparation;
         await Promise.allSettled([...this.calls]);
         await this.watchManager?.close();
         await this.work.close();

package/dist/cli/cli.js

@@ -53,7 +53,7 @@ export async function runCli(argv = process.argv) {
     const currentVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
     let application;
     let sendRequestId;
-    const app = (onReceiveProgress, sendRetry, onDestination) => application ??= new AttoApplication({ directory: program.opts().dataDir, onReceiveProgress, sendRetry, onDestination });
+    const app = (onReceiveProgress, sendRetry, onDestination) => application ??= new AttoApplication({ directory: program.opts().dataDir, onReceiveProgress, sendRetry, onDestination, workExecution: onReceiveProgress ? 'in-process' : 'detached' });
     const jsonOutput = (value) => { process.stdout.write(`${JSON.stringify(value, (_, value) => typeof value === 'bigint' ? value.toString() : value)}\n`); };
     const output = (result, operation) => {
         if (program.opts().json)
@@ -67,6 +67,7 @@ export async function runCli(argv = process.argv) {
             return diagnose(input);
         }
         const result = await app().call(name, compact(input));
+        app().resumeWork();
         output(result, name);
     };
     const waitForSignal = async (work) => {
@@ -166,8 +167,14 @@ export async function runCli(argv = process.argv) {
         if (program.opts().json)
             output({ displayed: true });
     });
-    wallet.command('receive').description('Keep automatic receiving running until Ctrl+C')
+    const receiveCommand = wallet.command('receive').description('Keep automatic receiving running until Ctrl+C')
+        .option('--background', 'Keep receiving after this terminal exits; restart manually after reboot')
         .action(async () => {
+        if (activeCommand.opts().background) {
+            const status = await app().startBackgroundReceiver();
+            output({ backgroundReceive: status }, 'wallet_receive');
+            return;
+        }
         const receiving = app(event => output(event, 'receive_progress'));
         const status = await receiving.call('wallet_status');
         if (!status.initialized)
@@ -183,6 +190,8 @@ export async function runCli(argv = process.argv) {
                 await new Promise(resolve => signal.addEventListener('abort', () => resolve(), { once: true }));
         });
     });
+    receiveCommand.command('status').description('Read detached receiver status').action(() => call('wallet_status'));
+    receiveCommand.command('stop').description('Request detached receiver shutdown').action(async () => output({ backgroundReceive: await app().stopBackgroundReceiver() }, 'wallet_receive'));
     const address = program.command('address').description('Manage mnemonic-derived public addresses');
     address.command('list').description('List all saved addresses and their activation state').action(() => call('address_list'));
     address.command('add').description('Add and activate the next account address; receiving funds opens it on the network').action(() => call('address_add'));
@@ -254,6 +263,7 @@ export async function runCli(argv = process.argv) {
                 signal,
                 onRetry: (error, delayMs) => progress({ requestId: sendRequestId, error: errorResult(error), retryInMs: delayMs }, `${error.message} Retrying in ${delayMs / 1000}s. Press Ctrl+C to stop.\n`),
             }, binding => progress({ requestId: sendRequestId, destination: binding.address, network: binding.network, ...(binding.label ? { personalName: binding.label } : {}) })).call('send', input);
+            app().resumeWork();
             output(result, 'send');
         });
     });
@@ -386,6 +396,7 @@ export async function runCli(argv = process.argv) {
         'atto wallet configure': 'atto wallet configure --node-url https://node-public.live.application.atto.cash --auto-receive',
         'atto wallet create': 'atto wallet create', 'atto wallet import': 'atto wallet import',
         'atto wallet reset': 'atto wallet reset', 'atto wallet backup': 'atto wallet backup', 'atto wallet receive': 'atto wallet receive',
+        'atto wallet receive status': 'atto wallet receive status', 'atto wallet receive stop': 'atto wallet receive stop',
         'atto address': 'atto address add\n  atto address list', 'atto address list': 'atto address list',
         'atto address add': 'atto address add', 'atto address derive': 'atto address derive 3',
         'atto address activate': 'atto address activate 1', 'atto address deactivate': 'atto address deactivate 1',

package/dist/cli/output.js

@@ -137,7 +137,7 @@ function formatUnlabeledHumanResult(result, operation) {
                 address: record(result.identity) ? result.identity.address : null,
                 network: result.settings.network,
                 automaticReceiving: result.settings.autoReceive ? 'Enabled' : 'Disabled',
-                ...(operation === 'wallet_status' ? { receivingInThisProcess: receiver.running, lastReceiveError: receiver.lastError } : {}),
+                ...(operation === 'wallet_status' ? { receivingInThisProcess: receiver.running, lastReceiveError: receiver.lastError, backgroundReceiver: result.backgroundReceive } : {}),
                 representative: result.settings.representative,
                 minReceiveRaw: result.settings.minReceiveRaw,
                 nodeUrl: result.settings.nodeUrl,

package/dist/spending/payments.js

@@ -333,15 +333,11 @@ export class Payments {
                     throw new AttoError('RECEIVABLE_NOT_PENDING', 'The consolidation transfer is not available to receive yet. Resume this payment with the same request ID.');
                 }
                 const transaction = await execution.wallet.receive(receivable, parseAddress(settings.representative), null);
-                const account = await execution.wallet.getAccountByIndex(toAttoIndex(index));
-                if (account)
-                    this.work.prepare([account]);
+                this.work.prepareConfirmed(transaction.block);
                 return transaction;
             }
             const transaction = await execution.wallet.sendByIndex(toAttoIndex(index), parseAddress(step?.destination ?? record.destination), AttoAmount.from(AttoUnit.RAW, step?.raw ?? record.raw), null);
-            const account = await execution.wallet.getAccountByIndex(toAttoIndex(index));
-            if (account)
-                this.work.prepare([account]);
+            this.work.prepareConfirmed(transaction.block);
             return transaction;
         }
         finally {
@@ -390,6 +386,7 @@ export class Payments {
             });
             if (outcome.status === 'rejected')
                 return;
+            this.work.prepareConfirmed(outcome.transaction.block);
         }
         if (!record.hash) {
             if (!record.plan)
@@ -403,6 +400,8 @@ export class Payments {
             else if (outcome.status === 'rejected')
                 this.ledger.reject(record.id);
         });
+        if (outcome.status === 'published')
+            this.work.prepareConfirmed(outcome.transaction.block);
     }
     async poolStatus() {
         const pool = this.ledger.pool();

package/dist/storage/state.d.ts

@@ -9,6 +9,7 @@ export declare class StateStore {
     private closed;
     private lockRequests;
     private exclusiveReset;
+    private auxiliaryLocks;
     get busy(): boolean;
     constructor(directory: string);
     get<T>(key: string): T | undefined;
@@ -28,5 +29,11 @@ export declare class StateStore {
     /** Acquire account locks first; short wallet reservations may run inside fn.
      * Closing the connection (including process death) releases every lock. */
     withAccountLocks<T>(indexes: readonly number[], fn: () => Promise<T>): Promise<T>;
+    /** A process lifetime lock.  Unlike the wallet mutation lock this has no
+     * bearing on ordinary commands, and SQLite releases it if the owner dies. */
+    tryProcessLock(name: string): (() => void) | undefined;
+    /** Computation locks never share the wallet/account mutation databases. */
+    tryWorkLock(target: string): (() => void) | undefined;
+    private tryAuxiliaryLock;
     close(): void;
 }

package/dist/storage/state.js

@@ -4,6 +4,20 @@ import { join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { setTimeout as delay } from 'node:timers/promises';
 import { AttoError } from '../domain/errors.js';
+import { createHash } from 'node:crypto';
+function ensureDatabaseFile(path) {
+    // Closing any raw descriptor for an existing SQLite file drops this process's
+    // POSIX locks, even when a different connection still owns the lease.
+    try {
+        closeSync(openSync(path, 'ax', 0o600));
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    if (process.platform !== 'win32')
+        chmodSync(path, 0o600);
+}
 export function defaultDataDirectory() {
     if (process.platform === 'win32')
         return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'Atto MCP');
@@ -21,6 +35,7 @@ export class StateStore {
     closed = false;
     lockRequests = 0;
     exclusiveReset = false;
+    auxiliaryLocks = 0;
     get busy() { return this.lockRequests !== 0 || this.exclusiveReset; }
     constructor(directory) {
         this.directory = resolve(directory);
@@ -28,9 +43,7 @@ export class StateStore {
         const connections = [];
         const open = (name) => {
             const path = join(this.directory, name);
-            closeSync(openSync(path, 'a', 0o600));
-            if (process.platform !== 'win32')
-                chmodSync(path, 0o600);
+            ensureDatabaseFile(path);
             const connection = new DatabaseSync(path);
             connections.push(connection);
             return connection;
@@ -93,7 +106,7 @@ export class StateStore {
      * store closes, even if another session prevents acquiring exclusivity. */
     async withExclusiveReset(fn) {
         this.requireOpen();
-        if (this.lockRequests !== 0 || this.exclusiveReset)
+        if (this.lockRequests !== 0 || this.auxiliaryLocks !== 0 || this.exclusiveReset)
             throw new AttoError('WALLET_BUSY', 'Wait for wallet operations before resetting this profile.');
         try {
             this.lifecycle.exec('ROLLBACK;');
@@ -192,9 +205,7 @@ export class StateStore {
             // Sorted acquisition prevents cycles when payments consolidate accounts.
             for (const index of [...new Set(indexes)].sort((left, right) => left - right)) {
                 const file = join(directory, `${index}.sqlite`);
-                closeSync(openSync(file, 'a', 0o600));
-                if (process.platform !== 'win32')
-                    chmodSync(file, 0o600);
+                ensureDatabaseFile(file);
                 const connection = new DatabaseSync(file);
                 connections.push(connection);
                 connection.exec('PRAGMA busy_timeout = 0; BEGIN IMMEDIATE;');
@@ -242,10 +253,52 @@ export class StateStore {
             }
         }
     }
+    /** A process lifetime lock.  Unlike the wallet mutation lock this has no
+     * bearing on ordinary commands, and SQLite releases it if the owner dies. */
+    tryProcessLock(name) {
+        if (!/^[a-z0-9-]{1,64}$/i.test(name))
+            throw new AttoError('INVALID_LOCK', 'Invalid process lock name.');
+        return this.tryAuxiliaryLock('process-locks', name);
+    }
+    /** Computation locks never share the wallet/account mutation databases. */
+    tryWorkLock(target) {
+        return this.tryAuxiliaryLock('work-locks', createHash('sha256').update(target).digest('hex'));
+    }
+    tryAuxiliaryLock(folder, name) {
+        this.requireOpen();
+        const directory = join(this.directory, folder);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = join(directory, `${name}.sqlite`);
+        ensureDatabaseFile(file);
+        const connection = new DatabaseSync(file);
+        try {
+            connection.exec('PRAGMA busy_timeout = 0; BEGIN IMMEDIATE;');
+        }
+        catch (error) {
+            connection.close();
+            const code = error.errcode;
+            if (code === 5 || code === 6)
+                return undefined;
+            throw error;
+        }
+        this.auxiliaryLocks++;
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            try {
+                connection.close();
+            }
+            finally {
+                this.auxiliaryLocks--;
+            }
+        };
+    }
     close() {
         if (this.closed)
             return;
-        if (this.lockRequests !== 0)
+        if (this.lockRequests !== 0 || this.auxiliaryLocks !== 0)
             throw new AttoError('WALLET_BUSY', 'Wait for wallet operations before closing state.');
         this.coordination.close();
         this.state.close();

package/dist/wallet/background-receive.d.ts

@@ -0,0 +1,30 @@
+import { errorResult } from '../domain/errors.js';
+import type { StateStore } from '../storage/state.js';
+import type { ReceiveProgress } from './auto-receive.js';
+interface ReceiverRecord {
+    token: string;
+    desired: boolean;
+    state: 'starting' | 'running' | 'stopping' | 'stopped';
+    lastError: ReturnType<typeof errorResult> | null;
+}
+export interface BackgroundReceiveStatus {
+    state: 'running' | 'stopping' | 'stopped';
+    lastError: ReturnType<typeof errorResult> | null;
+}
+export declare function requireReceivingProfile(store: StateStore): void;
+/** Profile control and observable process ownership. Persisted intent alone
+ * cannot make a receiver live or restart it after restoring a backup. */
+export declare class BackgroundReceiver {
+    private readonly store;
+    constructor(store: StateStore);
+    status(): BackgroundReceiveStatus;
+    start(): Promise<BackgroundReceiveStatus>;
+    stop(): Promise<BackgroundReceiveStatus>;
+    private launch;
+    /** A stale launch token cannot restart a stopped/reset/restored profile. */
+    claim(token: string): (() => void) | undefined;
+    stopping(token: string): boolean;
+    update(token: string, update: Partial<Omit<ReceiverRecord, 'token'>>): void;
+    progress(token: string, event: ReceiveProgress): void;
+}
+export {};

package/dist/wallet/background-receive.js

@@ -0,0 +1,117 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { AttoError, errorResult } from '../domain/errors.js';
+const KEY = 'receive.background';
+export function requireReceivingProfile(store) {
+    if (store.get('wallet.reset'))
+        throw new AttoError('WALLET_RESET_REQUIRED', 'Finish wallet reset before starting receiving.');
+    if (!store.get('identity'))
+        throw new AttoError('WALLET_NOT_INITIALIZED', 'Create or import a wallet before receiving: atto wallet create or atto wallet import.');
+    if (!store.get('settings')?.autoReceive)
+        throw new AttoError('AUTO_RECEIVE_DISABLED', 'Automatic receiving is disabled. Enable it with atto wallet configure --auto-receive.');
+    if (!store.get('addresses')?.some(address => address.active))
+        throw new AttoError('NO_ACTIVE_ACCOUNTS', 'Add or activate a wallet address before receiving.');
+}
+/** Profile control and observable process ownership. Persisted intent alone
+ * cannot make a receiver live or restart it after restoring a backup. */
+export class BackgroundReceiver {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    status() {
+        const record = this.store.get(KEY);
+        if (!record)
+            return { state: 'stopped', lastError: null };
+        const release = this.store.tryProcessLock('receive-daemon');
+        const live = !release;
+        release?.();
+        const lastError = record.lastError ?? (!live && record.state !== 'stopped'
+            ? errorResult(new AttoError('RECEIVER_EXITED', 'The background receiver exited. Start it again with atto wallet receive --background.')) : null);
+        return { state: live ? record.desired ? 'running' : 'stopping' : 'stopped', lastError };
+    }
+    async start() {
+        // Serialize launch/stop decisions, including startup acknowledgment. The
+        // child performs only local initialization before acknowledging this call.
+        return this.store.withWalletLock(async () => {
+            const status = this.status();
+            if (status.state !== 'stopped')
+                return status;
+            requireReceivingProfile(this.store);
+            const token = randomUUID();
+            this.store.set(KEY, { token, desired: true, state: 'starting', lastError: null });
+            try {
+                await this.launch(token);
+            }
+            catch (error) {
+                this.update(token, { desired: false, state: 'stopping', lastError: errorResult(error) });
+                throw error;
+            }
+            return this.status();
+        });
+    }
+    async stop() {
+        return this.store.withWalletLock(async () => {
+            const status = this.status();
+            const record = this.store.get(KEY);
+            if (record)
+                this.store.set(KEY, { ...record, desired: false, state: status.state === 'stopped' ? 'stopped' : 'stopping', lastError: status.lastError });
+            return { ...status, state: status.state === 'stopped' ? 'stopped' : 'stopping' };
+        });
+    }
+    launch(token) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [fileURLToPath(new URL('./receive-daemon.js', import.meta.url)), this.store.directory, token], {
+                detached: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'], windowsHide: true,
+            });
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (child.connected)
+                    child.disconnect();
+                child.unref();
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const timer = setTimeout(() => finish(new AttoError('RECEIVER_START_TIMEOUT', 'Background receiver initialization timed out. Check wallet receive status before retrying.')), 5000);
+            child.on('error', () => finish(new AttoError('RECEIVER_START_FAILED', 'The background receiver could not start. Check the installed CLI and profile permissions.')));
+            child.once('exit', () => finish(new AttoError('RECEIVER_START_FAILED', 'The background receiver exited before initialization completed. Check wallet receive status.')));
+            child.on('message', (message) => {
+                if (message && typeof message === 'object' && 'ready' in message && message.ready === token)
+                    finish();
+            });
+            child.unref();
+        });
+    }
+    /** A stale launch token cannot restart a stopped/reset/restored profile. */
+    claim(token) {
+        return this.store.transaction(() => {
+            if (this.stopping(token))
+                return;
+            return this.store.tryProcessLock('receive-daemon');
+        });
+    }
+    stopping(token) {
+        const record = this.store.get(KEY);
+        return record?.token !== token || !record.desired;
+    }
+    update(token, update) {
+        this.store.transaction(() => {
+            const record = this.store.get(KEY);
+            if (record?.token === token)
+                this.store.set(KEY, { ...record, ...update });
+        });
+    }
+    progress(token, event) {
+        if (event.event === 'retry' || event.event === 'reconnecting')
+            this.update(token, { lastError: event.error });
+        else if (event.event === 'received')
+            this.update(token, { lastError: null });
+    }
+}

package/dist/wallet/receive-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet/receive-daemon.js

@@ -0,0 +1,63 @@
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+const [directory, token] = process.argv.slice(2);
+if (directory && token) {
+    const { setTimeout: delay } = await import('node:timers/promises');
+    const { StateStore } = await import('../storage/state.js');
+    const { AttoApplication } = await import('../application/app.js');
+    const { BackgroundReceiver, requireReceivingProfile } = await import('./background-receive.js');
+    const { errorResult } = await import('../domain/errors.js');
+    let store;
+    let application;
+    let receiver;
+    let release;
+    const stop = () => receiver?.update(token, { desired: false, state: 'stopping' });
+    try {
+        store = new StateStore(directory);
+        receiver = new BackgroundReceiver(store);
+        release = receiver.claim(token);
+        if (release) {
+            requireReceivingProfile(store);
+            const owner = receiver;
+            application = new AttoApplication({
+                directory, receivingAllowed: () => !owner.stopping(token),
+                onReceiveProgress: event => owner.progress(token, event),
+            });
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            receiver.update(token, { state: 'running' });
+            // Acknowledge local construction/ownership before starting any network or
+            // password-store operation. IPC is detached immediately after the reply.
+            if (process.connected)
+                await new Promise((resolve, reject) => {
+                    process.send({ ready: token }, error => error ? reject(error) : resolve());
+                });
+            if (process.connected)
+                process.disconnect();
+            if (!receiver.stopping(token)) {
+                void application.start().catch(error => owner.update(token, { lastError: errorResult(error) }));
+                while (!receiver.stopping(token))
+                    await delay(100);
+            }
+        }
+    }
+    catch (error) {
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopping', lastError: errorResult(error) });
+    }
+    finally {
+        // Keep ownership and stopping visible until the current receive, startup
+        // lookups, and work requests have all finished or been canceled.
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopping' });
+        await application?.close();
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopped' });
+        release?.();
+        store?.close();
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        if (process.connected)
+            process.disconnect();
+    }
+}
+export {};

package/dist/wallet/work-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet/work-daemon.js

@@ -0,0 +1,20 @@
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+const [directory, epoch] = process.argv.slice(2);
+if (directory && epoch) {
+    const { StateStore } = await import('../storage/state.js');
+    const { WalletWork } = await import('./work.js');
+    let store;
+    let work;
+    try {
+        store = new StateStore(directory);
+        const state = store;
+        work = new WalletWork(state, () => state.get('settings'));
+        await work.runDetached(epoch);
+    }
+    catch { /* Public jobs remain eligible after startup or storage failures. */ }
+    finally {
+        await work?.close();
+        store?.close();
+    }
+}
+export {};

package/dist/wallet/work.d.ts

@@ -5,25 +5,47 @@ export interface BlockWorker {
     workBlock(block: AttoBlock, signal?: AbortSignal): Promise<AttoWork>;
     close(): void;
 }
-/** Public work only: no signer, mnemonic, or seed enters this owner. */
+export type WorkExecution = 'in-process' | 'detached';
+/** Public preparation, validation and caching. No credential or signer enters
+ * this owner. Speculative failures never escape into completed transactions. */
 export declare class WalletWork {
     private readonly store;
     private readonly settings;
-    private readonly queued;
-    private readonly pending;
-    private readonly requests;
-    private backgroundCount;
+    private readonly execution;
     private closed;
-    constructor(store: StateStore, settings: () => WalletSettings);
+    private drainTask?;
+    private resumeRequested;
+    private readonly active;
+    private readonly computations;
+    private readonly requests;
+    constructor(store: StateStore, settings: () => WalletSettings, execution?: WorkExecution);
+    private scope;
+    private nextBlock;
+    private key;
+    private head;
+    private same;
     isReady(account: AttoAccount): boolean;
     prepare(accounts: readonly AttoAccount[]): void;
+    /** A confirmed block is sufficient to prepare its successor, including after
+     * publication recovery. This unsigned change template is never published;
+     * work depends on the head, height, network and time, not its representative. */
+    prepareConfirmed(block: AttoBlock): void;
+    private enqueue;
+    /** Resume only after successful CLI input validation/operation, never in the constructor. */
+    resume(): void;
     worker(): BlockWorker;
-    close(): Promise<void>;
-    private nextBlock;
-    private key;
+    private queue;
+    /** Caller owns the short state transaction. Lower observations cannot undo
+     * newer heads; an equal-height replacement invalidates the previous fork. */
+    private observe;
     private read;
     private save;
     private obtain;
     private compute;
+    /** Release the singleton inside the final queue transaction. An enqueue is
+     * either seen by this owner or its launch candidate can become the next owner. */
+    runDetached(epoch: string): Promise<void>;
     private drain;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
 }

package/dist/wallet/work.js

@@ -1,62 +1,153 @@
-import { AttoInstant, AttoWork, attoAccountChange, attoBlockWorkTarget, } from '@attocash/commons-core';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { AttoBlock, AttoChangeBlock, AttoInstant, AttoWork, attoAccountChange, attoBlockWorkTarget, toAttoHeight } from '@attocash/commons-core';
 import { requestWork } from '../network/work.js';
 import { AttoError } from '../domain/errors.js';
-const BACKGROUND_LIMIT = 2;
+const QUEUE_KEY = 'work.queue';
+const EPOCH_KEY = 'work.epoch';
 const QUEUE_LIMIT = 100;
-/** Public work only: no signer, mnemonic, or seed enters this owner. */
+const CONCURRENCY = 2;
+const SPECULATIVE_MS = 10_000;
+const WORKER_MS = 60_000;
+/** Public preparation, validation and caching. No credential or signer enters
+ * this owner. Speculative failures never escape into completed transactions. */
 export class WalletWork {
     store;
     settings;
-    queued = new Map();
-    pending = new Map();
-    requests = new Set();
-    backgroundCount = 0;
+    execution;
     closed = false;
-    constructor(store, settings) {
+    drainTask;
+    resumeRequested = false;
+    active = new Set();
+    computations = new Map();
+    requests = new Set();
+    constructor(store, settings, execution = 'in-process') {
         this.store = store;
         this.settings = settings;
+        this.execution = execution;
+    }
+    scope() {
+        const { network, nodeUrl, workerUrl } = this.settings();
+        return JSON.stringify([this.store.get(EPOCH_KEY) ?? null, this.store.get('identity') ?? null, network, nodeUrl, workerUrl]);
+    }
+    nextBlock(account) {
+        return attoAccountChange(account, account.representativeAddress, AttoInstant.Companion.now().toString()).block;
     }
+    key(block) { return `work.${block.network.name}.${block.publicKey}`; }
+    head(block) { return { scope: this.scope(), target: attoBlockWorkTarget(block), height: block.height.toString() }; }
+    same(left, right) { return left.scope === right.scope && left.target === right.target && left.height === right.height; }
     isReady(account) {
-        if (this.closed || account.network.name !== this.settings().network)
+        try {
+            return !this.closed && account.network.name === this.settings().network && Boolean(this.read(this.nextBlock(account)));
+        }
+        catch {
             return false;
-        return this.read(this.nextBlock(account)) !== undefined;
+        }
     }
     prepare(accounts) {
+        try {
+            this.enqueue(accounts.map(account => this.nextBlock(account)));
+        }
+        catch { /* Public preparation must not change a completed payment's result. */ }
+    }
+    /** A confirmed block is sufficient to prepare its successor, including after
+     * publication recovery. This unsigned change template is never published;
+     * work depends on the head, height, network and time, not its representative. */
+    prepareConfirmed(block) {
+        try {
+            this.enqueue([new AttoChangeBlock(block.network, block.version, block.algorithm, block.publicKey, toAttoHeight((BigInt(block.height.toString()) + 1n).toString()), block.balance, AttoInstant.Companion.now(), block.hash, block.algorithm, block.publicKey)]);
+        }
+        catch { /* Even template/storage failures are optional after confirmation. */ }
+    }
+    enqueue(blocks) {
         if (this.closed)
             return;
-        for (const account of accounts) {
-            if (account.network.name !== this.settings().network)
-                continue;
-            const block = this.nextBlock(account);
-            if (this.read(block))
-                continue;
-            const key = this.key(block);
-            if (this.queued.size < QUEUE_LIMIT || this.queued.has(key))
-                this.queued.set(key, block);
-        }
-        this.drain();
+        try {
+            this.store.transaction(() => {
+                if (!this.store.get(EPOCH_KEY))
+                    this.store.set(EPOCH_KEY, randomUUID());
+                let queue = this.queue();
+                for (const block of blocks) {
+                    if (block.network.name !== this.settings().network)
+                        continue;
+                    const key = this.key(block);
+                    const head = this.head(block);
+                    if (!this.observe(key, head))
+                        continue;
+                    queue = queue.filter(job => job.scope === head.scope);
+                    const position = queue.findIndex(job => job.key === key);
+                    if (this.read(block)) {
+                        queue = queue.filter(job => job.key !== key || !this.same(job, head));
+                    }
+                    else if (position !== -1) {
+                        if (!this.same(queue[position], head))
+                            queue[position] = { ...head, key, id: randomUUID(), block: block.toJson() };
+                    }
+                    else if (queue.length < QUEUE_LIMIT)
+                        queue.push({ ...head, key, id: randomUUID(), block: block.toJson() });
+                }
+                this.store.set(QUEUE_KEY, queue);
+            });
+            this.resume();
+        }
+        catch { /* A completed transaction survives speculative storage/launch failures. */ }
+    }
+    /** Resume only after successful CLI input validation/operation, never in the constructor. */
+    resume() {
+        if (this.closed)
+            return;
+        try {
+            if (!this.queue().length)
+                return;
+            if (this.execution === 'detached') {
+                // Always launch a candidate after enqueueing. The child checks ownership
+                // in the same state transaction used by the draining owner's exit.
+                const child = spawn(process.execPath, [fileURLToPath(new URL('./work-daemon.js', import.meta.url)), this.store.directory, this.store.get(EPOCH_KEY) ?? ''], {
+                    detached: true, stdio: 'ignore', windowsHide: true,
+                });
+                child.on('error', () => { });
+                child.unref();
+            }
+            else if (this.drainTask)
+                this.resumeRequested = true;
+            else {
+                this.resumeRequested = false;
+                this.drainTask = this.drain().catch(() => { }).finally(() => {
+                    this.drainTask = undefined;
+                    if (this.resumeRequested)
+                        this.resume();
+                });
+            }
+        }
+        catch { /* Pending jobs remain eligible on a later invocation. */ }
     }
     worker() {
-        // A signing operation borrows this cache; only the application closes it.
         return { workBlock: (block, signal) => this.obtain(block, false, signal), close() { } };
     }
-    async close() {
-        this.closed = true;
-        this.queued.clear();
-        for (const request of this.requests)
-            request.abort();
-        await Promise.allSettled([...this.pending.values()].map(job => job.promise));
+    queue() {
+        const value = this.store.get(QUEUE_KEY);
+        if (!Array.isArray(value))
+            return [];
+        return value.filter((job) => job !== null && typeof job === 'object'
+            && ['id', 'key', 'scope', 'target', 'block'].every(key => typeof job[key] === 'string')
+            && typeof job.height === 'string' && /^\d+$/.test(job.height)).slice(0, QUEUE_LIMIT);
     }
-    nextBlock(account) {
-        // Commons constructs the next-head target and validates its own work. This
-        // unsigned block is only a work request; it is never signed or published.
-        return attoAccountChange(account, account.representativeAddress, AttoInstant.Companion.now().toString()).block;
+    /** Caller owns the short state transaction. Lower observations cannot undo
+     * newer heads; an equal-height replacement invalidates the previous fork. */
+    observe(key, head) {
+        const prior = this.store.get('head.' + key);
+        if (prior?.scope === head.scope && /^\d+$/.test(prior.height) && BigInt(prior.height) > BigInt(head.height))
+            return false;
+        this.store.set('head.' + key, head);
+        return true;
     }
-    key(block) { return `work.${block.network.name}.${block.publicKey.toString()}`; }
     read(block) {
         try {
             const record = this.store.get(this.key(block));
-            if (!record || record.target !== attoBlockWorkTarget(block) || !/^[0-9a-f]{16}$/i.test(record.work))
+            if (!record || !this.same(record, this.head(block)) || !/^[0-9a-f]{16}$/i.test(record.work))
                 return;
             const work = AttoWork.Companion.parse(record.work);
             return work.isValid(block) ? work : undefined;
@@ -65,63 +156,126 @@ export class WalletWork {
             return undefined;
         }
     }
-    save(block, work) {
-        if (this.closed || block.network.name !== this.settings().network)
+    save(block, head, work) {
+        if (this.closed || this.scope() !== head.scope)
             return;
-        const key = this.key(block);
         this.store.transaction(() => {
-            const prior = this.store.get(key);
-            // An older in-flight job must not displace work for a newer account head,
-            // including work another CLI/MCP process has already persisted.
-            if (prior && /^\d+$/.test(prior.height) && BigInt(prior.height) > BigInt(block.height.toString()))
+            const observed = this.store.get('head.' + this.key(block));
+            if (observed && !this.same(observed, head))
                 return;
-            this.store.set(key, { target: attoBlockWorkTarget(block), height: block.height.toString(), work: work.toString() });
+            this.store.set(this.key(block), { scope: head.scope, target: head.target, height: head.height, work: work.toString() });
+            this.store.set(QUEUE_KEY, this.queue().filter(job => job.key !== this.key(block) || !this.same(job, head)));
         });
     }
-    async obtain(block, speculative = false, signal) {
-        if (this.closed)
-            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
-        const settings = this.settings();
-        if (block.network.name !== settings.network)
-            throw new AttoError('NETWORK_MISMATCH', 'Work must use the configured wallet network.');
-        const ready = this.read(block);
-        if (ready)
-            return ready;
-        const key = `${this.key(block)}.${attoBlockWorkTarget(block)}`;
-        const existing = this.pending.get(key);
+    async obtain(block, speculative, signal) {
+        // Establish the shared generation before any computation takes its lock.
+        // Otherwise a first enqueue could change its scope while foreground work
+        // was already running under an uninitialized generation.
+        if (!this.store.get(EPOCH_KEY)) {
+            try {
+                this.store.transaction(() => { if (!this.store.get(EPOCH_KEY))
+                    this.store.set(EPOCH_KEY, randomUUID()); });
+            }
+            catch { /* Foreground work can still use its ordinary uncached fallback. */ }
+        }
+        const key = this.scope() + ':' + this.key(block) + ':' + attoBlockWorkTarget(block);
+        const existing = this.computations.get(key);
         if (existing) {
+            let cancel;
             try {
-                const work = await existing.promise;
-                // A job begun before a threshold change may no longer satisfy this block.
+                const cancelled = new Promise((_, reject) => {
+                    cancel = () => reject(new AttoError('CANCELLED', 'Send cancelled.'));
+                    if (signal?.aborted)
+                        cancel();
+                    else
+                        signal?.addEventListener('abort', cancel, { once: true });
+                });
+                const work = await Promise.race([existing.promise, cancelled]);
                 if (work.isValid(block))
                     return work;
             }
             catch (error) {
-                // Speculation has a shorter deadline. A real transaction retains the
-                // normal worker budget if that earlier background attempt failed.
-                if (speculative || !existing.speculative)
+                if (signal?.aborted || speculative || !existing.speculative)
                     throw error;
             }
+            finally {
+                if (cancel)
+                    signal?.removeEventListener('abort', cancel);
+            }
         }
-        if (this.closed)
-            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
-        const job = { promise: this.compute(block, settings.workerUrl, speculative ? 10 : 60, signal), speculative };
-        this.pending.set(key, job);
+        const operation = this.compute(block, speculative, signal);
+        this.active.add(operation);
+        const computation = { promise: operation, speculative };
+        this.computations.set(key, computation);
         try {
-            return await job.promise;
+            return await operation;
         }
         finally {
-            if (this.pending.get(key) === job)
-                this.pending.delete(key);
+            this.active.delete(operation);
+            if (this.computations.get(key) === computation)
+                this.computations.delete(key);
         }
     }
-    async compute(block, url, timeoutSeconds, signal) {
+    async compute(block, speculative, signal) {
+        if (this.closed)
+            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
+        const settings = this.settings();
+        if (block.network.name !== settings.network)
+            throw new AttoError('NETWORK_MISMATCH', 'Work must use the configured wallet network.');
+        const head = this.head(block);
         const controller = new AbortController();
         this.requests.add(controller);
-        const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+        const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
+        let timer = setTimeout(() => controller.abort(), speculative ? SPECULATIVE_MS : WORKER_MS);
+        let release;
+        let slot;
         try {
-            const work = await requestWork(block, url, AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]));
-            this.save(block, work);
+            if (!speculative) {
+                try {
+                    this.store.transaction(() => this.observe(this.key(block), head));
+                }
+                catch { /* Coordination/cache failure falls back to foreground generation. */ }
+            }
+            for (;;) {
+                combined.throwIfAborted();
+                if (this.scope() !== head.scope)
+                    throw new AttoError('WORK_OBSOLETE', 'Wallet configuration changed during work preparation.');
+                const ready = this.read(block);
+                if (ready)
+                    return ready;
+                try {
+                    release = this.store.tryWorkLock(head.scope + ':' + this.key(block) + ':' + head.target);
+                }
+                catch (error) {
+                    if (speculative)
+                        throw error;
+                    break;
+                }
+                if (release)
+                    break;
+                await delay(25, undefined, { signal: combined });
+            }
+            if (speculative) {
+                while (!slot) {
+                    for (let index = 0; index < CONCURRENCY && !slot; index++)
+                        slot = this.store.tryWorkLock('speculative-slot-' + index);
+                    if (!slot)
+                        await delay(25, undefined, { signal: combined });
+                }
+            }
+            else {
+                // Waiting for speculation does not consume the normal generation budget.
+                clearTimeout(timer);
+                timer = setTimeout(() => controller.abort(), WORKER_MS);
+            }
+            const ready = this.read(block);
+            if (ready)
+                return ready;
+            const work = await requestWork(block, settings.workerUrl, combined);
+            try {
+                this.save(block, head, work);
+            }
+            catch { /* The validated nonce remains usable. */ }
             return work;
         }
         catch (error) {
@@ -138,17 +292,92 @@ export class WalletWork {
         finally {
             clearTimeout(timer);
             this.requests.delete(controller);
+            slot?.();
+            release?.();
         }
     }
-    drain() {
-        while (!this.closed && this.backgroundCount < BACKGROUND_LIMIT && this.queued.size > 0) {
-            const [key, block] = this.queued.entries().next().value;
-            this.queued.delete(key);
-            this.backgroundCount++;
-            void this.obtain(block, true).catch(() => { }).finally(() => {
-                this.backgroundCount--;
-                this.drain();
-            });
+    /** Release the singleton inside the final queue transaction. An enqueue is
+     * either seen by this owner or its launch candidate can become the next owner. */
+    async runDetached(epoch) {
+        let release;
+        this.store.transaction(() => {
+            if (this.store.get(EPOCH_KEY) === epoch)
+                release = this.store.tryProcessLock('work-daemon');
+        });
+        if (!release)
+            return;
+        const unlock = () => { release?.(); release = undefined; };
+        try {
+            await this.drain(epoch, unlock);
+        }
+        finally {
+            await this.close();
+            unlock();
+        }
+    }
+    async drain(epoch = this.store.get(EPOCH_KEY), unlock) {
+        const attempted = new Set();
+        const pending = new Map();
+        const started = performance.now();
+        try {
+            for (;;) {
+                if (this.closed || this.store.get(EPOCH_KEY) !== epoch || (unlock && performance.now() - started >= WORKER_MS))
+                    break;
+                const jobs = this.store.transaction(() => {
+                    const queue = this.queue().filter(job => job.scope === this.scope());
+                    this.store.set(QUEUE_KEY, queue);
+                    const next = queue.filter(job => !attempted.has(job.id)).slice(0, CONCURRENCY - pending.size);
+                    if (!next.length && !pending.size)
+                        unlock?.();
+                    return next;
+                });
+                if (!jobs.length && !pending.size)
+                    return;
+                for (const job of jobs) {
+                    attempted.add(job.id);
+                    const task = (async () => {
+                        const template = AttoBlock.fromJson(job.block);
+                        if (!(template instanceof AttoChangeBlock))
+                            return;
+                        const block = new AttoChangeBlock(template.network, template.version, template.algorithm, template.publicKey, template.height, template.balance, AttoInstant.Companion.now(), template.previous, template.representativeAlgorithm, template.representativePublicKey);
+                        const observed = this.store.get('head.' + job.key);
+                        if (this.key(block) !== job.key || !this.same(this.head(block), job) || (observed && !this.same(observed, job)))
+                            return;
+                        const work = await this.obtain(block, true);
+                        // Cache hits also remove jobs left by interrupted owners.
+                        this.save(block, job, work);
+                    })().catch(() => { }).finally(() => pending.delete(job.id));
+                    pending.set(job.id, task);
+                }
+                await Promise.race([...pending.values(), delay(25)]);
+            }
         }
+        finally {
+            if (unlock)
+                for (const controller of this.requests)
+                    controller.abort();
+            await Promise.allSettled([...pending.values()]);
+        }
+    }
+    async cancel() {
+        this.store.transaction(() => { this.store.set(EPOCH_KEY, randomUUID()); this.store.set(QUEUE_KEY, []); });
+        await this.close();
+        const deadline = performance.now() + 5000;
+        for (;;) {
+            const release = this.store.tryProcessLock('work-daemon');
+            if (release) {
+                release();
+                return;
+            }
+            if (performance.now() >= deadline)
+                throw new AttoError('WALLET_BUSY', 'Public work preparation is still stopping. Retry wallet reset.');
+            await delay(25);
+        }
+    }
+    async close() {
+        this.closed = true;
+        for (const controller of this.requests)
+            controller.abort();
+        await Promise.allSettled([...this.active, ...(this.drainTask ? [this.drainTask] : [])]);
     }
 }

package/dist/watches/manager.d.ts

@@ -28,7 +28,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;
@@ -40,7 +40,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;
@@ -60,7 +60,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attocash/cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Atto wallet CLI and reusable wallet engine with local key custody and shared spending limits",
   "license": "BSD-3-Clause",
   "type": "module",