@attocash/cli 0.1.1 → 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
@@ -736,13 +775,13 @@ git clone https://github.com/attocash/integrations.git
 cd integrations
 npm ci
 npm run pack
-npm install --global ./attocash-cli-0.1.1.tgz
+npm install --global ./attocash-cli-0.0.0.tgz
 ```
 
 To test MCP with the same local CLI build, install both artifacts together:
 
 ```sh
-npm install --global ./attocash-cli-0.1.1.tgz ./attocash-mcp-0.1.1.tgz
+npm install --global ./attocash-cli-0.0.0.tgz ./attocash-mcp-0.0.0.tgz
 ```
 
 For development and testing, see the [contributor guide](https://github.com/attocash/integrations/blob/main/docs/contributing.md).

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/onboarding.d.ts

@@ -8,7 +8,6 @@ interface ProposalOptions {
 export declare function approveLimitsProposal({ id, directory }: ProposalOptions): Promise<unknown>;
 export declare function rejectLimitsProposal({ id, directory }: ProposalOptions): Promise<unknown>;
 /** Returns only public host configuration; recovery material is displayed directly on the TTY. */
-export declare function setupMcp({ version, directory }: {
-    version: string;
+export declare function setupMcp({ directory }: {
     directory?: string;
 }): Promise<unknown>;

package/dist/cli/onboarding.js

@@ -107,7 +107,7 @@ async function configurePool(current) {
     return { indexes, consolidate };
 }
 /** Returns only public host configuration; recovery material is displayed directly on the TTY. */
-export async function setupMcp({ version, directory }) {
+export async function setupMcp({ directory }) {
     requireTerminal();
     process.stderr.write('Atto MCP setup. Recovery phrases stay in your OS password store and this terminal.\n');
     const wallet = await choose('Wallet: [1] Dedicated MCP wallet (default), [2] Existing CLI wallet: ');
@@ -136,7 +136,7 @@ export async function setupMcp({ version, directory }) {
         const { proposal } = await application.call('limits_propose', { policy, access, pool });
         await approve(application, proposal.id);
         process.stderr.write('\nAdd this public configuration to your MCP client. The explicit data directory preserves your wallet selection.\n');
-        return { mcpServers: { atto: { command: 'npx', args: ['--yes', `@attocash/mcp@${version}`, '--data-dir', profile.directory] } } };
+        return { mcpServers: { atto: { command: 'npx', args: ['--yes', '@attocash/mcp@latest', '--data-dir', profile.directory] } } };
     }
     finally {
         await application.close();

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 });
+    }
+}