@superjackfruitlabs/salaam 0.0.4 → 0.0.5

package/dist/src/local-coding.js

@@ -3,13 +3,20 @@ import { sandboxArgv, seatbeltArgv, UNSANDBOXED_REFUSAL, } from './command-sandb
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
+import { classifyCommand } from './command-danger.js';
+import { gitIdentityEnv, publishesToRemote } from './git-helpers.js';
+import { boundShellCommand } from './shell-passthrough.js';
 import { join } from 'node:path';
 import { digest, object, string, ServiceError } from './protocol.js';
-import { prepareLocalEdits, verifyLocalEdits, applyLocalEdits, } from './local-edits.js';
-import { permissionPolicy, permissionDigest, matchesEditScope, assertPermissionBinding, } from './autonomy.js';
+import { prepareLocalEdits, verifyLocalEdits, applyLocalEdits, reviewLocalEdits, } from './local-edits.js';
+import { permissionPolicy, autoApprovesEdits, autoApprovesCommands, permissionDigest, assertPermissionBinding, } from './autonomy.js';
+import { commandArgv, evaluateRules, } from './approval-rules.js';
 import { assertUndoSettled } from './local-undo.js';
-import { processIdentity } from './supervisor.js';
+import { processIdentity, processStart } from './supervisor.js';
+const TASK_TAIL = 65536;
+const TASK_LIMIT = 4;
+const BACKGROUND_LIFETIME = 2 * 3600 * 1000;
 import { applyEditsAsTools, killToolGroup, serviceToolIdentity, toolArgv, } from './tool-identity.js';
 /** The proxy a broker-network command uses: only the relay on loopback, nothing direct. */
 function proxyEnv(port) {
@@ -30,8 +37,21 @@ export class LocalCoding {
     tools;
     sandbox;
     jobs = new Map();
+    /** Background tasks this controller owns; they belong to the session, not to a turn. */
+    live = new Map();
+    /** Output of recently ended tasks, so the model can read why one stopped. */
+    kept = new Map();
+    /** Background commands are for a person's own desk session only (Phase 3c). */
+    interactive = () => false;
     closed = false;
     unregister;
+    /** Desk-session approval rules (allow/ask/deny), set by the service; absent means every request asks. */
+    rules;
+    /** Operator ruling 2026-11-01 (option 1): one command may ask to run outside the OS sandbox.
+     * Off where the host forbids full access, since it is full access for that one command. */
+    allowOutsideSandbox = true;
+    /** The optional small-model command reviewer (Phase 4c); absent means the rules alone decide. */
+    classifier;
     constructor(store, managed, active, tools = serviceToolIdentity(), 
     /** Chosen by the service from the host and the operator's setting. */
     sandbox = { kind: 'none', level: 'full-access', bwrap: null }) {
@@ -51,6 +71,19 @@ export class LocalCoding {
                     throw new ServiceError('local_busy', 'Command resources are still active');
             },
         });
+        store.db.exec('CREATE TABLE IF NOT EXISTS local_tasks(id TEXT PRIMARY KEY,session_id TEXT NOT NULL,call_id TEXT NOT NULL,command TEXT NOT NULL,state TEXT NOT NULL,pid INTEGER,identity TEXT,exit_code INTEGER,started_at TEXT NOT NULL,ended_at TEXT)');
+        // A background task never outlives its controller: kill what a restart left and say so.
+        for (const raw of store.db.prepare("SELECT * FROM local_tasks WHERE state='running'").all()) {
+            const t = raw;
+            if (t.pid && t.identity && processStart(t.pid) === t.identity)
+                try {
+                    process.kill(-t.pid, 'SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            this.endTask(t, 'lost', null);
+        }
         // A lost controller must never retry a possibly executed edit or command.
         for (const raw of store.db.prepare("SELECT * FROM local_calls WHERE state='running'").all()) {
             const c = raw;
@@ -73,6 +106,22 @@ export class LocalCoding {
             });
         }
     }
+    /** The exact edits an edit request carries, or none for a command; files over 256 KiB are left out. */
+    edits(session, by) {
+        const row = this.store.db
+            .prepare(`SELECT root,args FROM local_calls WHERE session_id=? AND ${'operation' in by ? 'operation_id' : 'tool_call'}=? ORDER BY rowid DESC LIMIT 1`)
+            .get(session, 'operation' in by ? by.operation : by.toolCall);
+        if (!row)
+            return null;
+        const args = object(JSON.parse(row.args));
+        if (args.action !== 'edit')
+            return null;
+        const small = (text) => text === null || Buffer.byteLength(text) <= 256 * 1024;
+        return {
+            root: row.root,
+            edits: args.edits.filter((e) => small(e.before) && small(e.after)),
+        };
+    }
     get(id) {
         const row = this.store.db.prepare('SELECT * FROM local_calls WHERE id=?').get(id);
         if (!row)
@@ -114,7 +163,51 @@ export class LocalCoding {
             .get(c.root, c.id))
             throw new ServiceError('local_busy', 'Another operation or uncertain outcome owns this workspace');
     }
-    prepare(session, epoch, attempt, toolCall, input) {
+    /** prepare, after the optional reviewer has looked at a command the session would run unasked. */
+    async prepareReviewed(session, epoch, attempt, toolCall, input) {
+        let review = null;
+        if (this.classifier && input.action === 'command' && typeof input.command === 'string') {
+            const p = permissionPolicy(this.store, session);
+            // Only where the mode would run the command without asking; review mode asks anyway.
+            if (p.access || p.mode === 'auto') {
+                const root = this.store.session(session).cwd;
+                if (!classifyCommand(input.command, this.dangerContext(root)).dangerous)
+                    review = await this.classifier.review(session, input.command, root);
+            }
+        }
+        return this.prepare(session, epoch, attempt, toolCall, input, review);
+    }
+    dangerContext(root) {
+        return {
+            root,
+            home: homedir(),
+            tmp: [...new Set(['/tmp', '/private/tmp', tmpdir(), realpathSync(tmpdir())])],
+        };
+    }
+    /** Has this tool call already been prepared? */
+    hasCall(session, epoch, toolCall) {
+        return !!this.store.db
+            .prepare('SELECT 1 FROM local_calls WHERE session_id=? AND epoch=? AND tool_call=?')
+            .get(session, epoch, toolCall);
+    }
+    /** A `!command` turn runs only what was typed, once (trial polish #12): enforced here, not by
+     * the model following its instruction, so it holds in auto, full access and YOLO alike. */
+    assertShellBinding(session, attempt, input) {
+        const row = this.store.db
+            .prepare('SELECT s.text FROM attempts a JOIN submissions s ON s.id=a.submission_id WHERE a.id=? AND a.session_id=?')
+            .get(attempt, session);
+        const bound = row ? boundShellCommand(row.text) : undefined;
+        if (bound === undefined)
+            return;
+        if (input.action !== 'command' || input.command !== bound || input.background)
+            throw new ServiceError('shell_binding', `This turn runs only the command you typed: ${bound}. Run exactly that, unchanged.`);
+        const ran = this.store.db
+            .prepare('SELECT 1 FROM local_calls WHERE session_id=? AND attempt_id=?')
+            .get(session, attempt);
+        if (ran)
+            throw new ServiceError('shell_binding', 'This turn already ran the command you typed. Report its output; do not run anything else.');
+    }
+    prepare(session, epoch, attempt, toolCall, input, review = null) {
         const prior = this.store.db
             .prepare('SELECT id,input_digest FROM local_calls WHERE session_id=? AND epoch=? AND tool_call=?')
             .get(session, epoch, toolCall);
@@ -123,6 +216,7 @@ export class LocalCoding {
                 throw new ServiceError('request_conflict', 'Tool call already binds different arguments');
             return this.view(String(prior.id));
         }
+        this.assertShellBinding(session, attempt, input);
         const root = this.store.session(session).cwd;
         const c = {
             id: randomUUID(),
@@ -148,36 +242,72 @@ export class LocalCoding {
             const timeout = input.timeout_ms ?? 30000;
             if (!Number.isInteger(timeout) || Number(timeout) < 100 || Number(timeout) > 120000)
                 throw new ServiceError('invalid_field', 'Command timeout must be 100–120000 ms');
-            if (this.sandbox.kind === 'bwrap' &&
-                this.sandbox.level !== 'full-access' &&
-                !this.sandbox.bwrap)
+            const background = input.background === true;
+            if (input.background !== undefined && typeof input.background !== 'boolean')
+                throw new ServiceError('invalid_field', 'background must be true or false');
+            if (background)
+                this.assertBackground(session);
+            if (input.listen !== undefined && typeof input.listen !== 'boolean')
+                throw new ServiceError('invalid_field', 'listen must be true or false');
+            if (input.outside_sandbox !== undefined &&
+                (typeof input.outside_sandbox !== 'string' || !input.outside_sandbox.trim()))
+                throw new ServiceError('invalid_field', 'outside_sandbox must say why the command needs to run without the sandbox');
+            const session_sb = this.sandboxFor(session);
+            // Only a sandboxed session has anything to step out of; under full access it changes nothing.
+            const outside = typeof input.outside_sandbox === 'string' && this.sandboxed(session_sb)
+                ? input.outside_sandbox.trim().slice(0, 300)
+                : undefined;
+            if (outside !== undefined && (!this.allowOutsideSandbox || this.tools.mode === 'tools-user'))
+                throw new ServiceError('outside_sandbox_denied', 'The operator does not allow commands outside the OS sandbox on this host. Ask the person to run it themselves.');
+            const sb = outside !== undefined ? { ...session_sb, level: 'full-access' } : session_sb;
+            // Operator ruling 2026-11-01 (option C): a sandboxed command listens only when a person
+            // approves that exact command to. Linux's sandbox has its own network, so it cannot serve.
+            const listen = input.listen === true && this.sandboxed(sb);
+            if (listen && sb.kind === 'bwrap')
+                throw new ServiceError('listen_unreachable', 'On Linux the command sandbox has its own network namespace, so a server it starts cannot be reached from the host. Ask for full access for this command, or run the server yourself.');
+            if (sb.kind === 'bwrap' && sb.level !== 'full-access' && !sb.bwrap)
                 throw new ServiceError('sandbox_unavailable', 'This host has no usable bubblewrap, so it cannot run a sandboxed command; an operator can choose full access explicitly');
-            if (this.sandbox.kind === 'none' &&
-                this.sandbox.level !== 'full-access' &&
-                !this.sandbox.allowUnsandboxed)
+            if (sb.kind === 'none' && sb.level !== 'full-access' && !sb.allowUnsandboxed)
                 throw new ServiceError('sandbox_unavailable', UNSANDBOXED_REFUSAL);
             args = {
                 action: 'command',
                 command: string(input.command, 'command', 8192),
-                timeout_ms: Number(timeout),
+                timeout_ms: background ? BACKGROUND_LIFETIME : Number(timeout),
+                ...(background ? { background: true } : {}),
+                ...(listen ? { listen: true } : {}),
+                ...(outside !== undefined ? { outside_sandbox: outside } : {}),
                 // Bound into the approval and the operation digest: the sandbox is part of what is approved.
                 sandbox: {
-                    kind: this.sandbox.kind,
-                    level: this.sandbox.level,
-                    bwrap: this.sandbox.bwrap?.version ?? null,
-                    ...(this.brokerNetwork() ? { network: 'broker' } : {}),
+                    kind: sb.kind,
+                    level: sb.level,
+                    bwrap: sb.bwrap?.version ?? null,
+                    ...(this.brokerNetwork(sb) ? { network: 'broker' } : {}),
                 },
             };
         }
         else
             throw new ServiceError('invalid_field', 'Choose edit or command');
         c.args = JSON.stringify(args);
+        // Operator ruling 2026-10-31: full access asks only for commands this check calls dangerous.
+        const rulesDanger = args.action === 'command'
+            ? classifyCommand(args.command, this.dangerContext(root))
+            : { dangerous: false };
+        // Phase 4c: the reviewer can only add a reason to ask, never remove one.
+        const escalated = !rulesDanger.dangerous && args.action === 'command' && !!review?.escalate;
+        const danger = escalated
+            ? {
+                dangerous: true,
+                category: 'classifier',
+                reason: `${review.reason} (reviewed by ${review.model})`,
+                segment: args.command,
+            }
+            : rulesDanger;
+        // Pushing and opening a pull request ask in every mode but YOLO (operator ruling 2026-10-31).
+        const publishes = args.action === 'command' ? publishesToRemote(args.command) : null;
         this.store.transaction(() => {
             const reviewed = args.action === 'edit'
-                ? args.edits
-                    .map((e) => `--- ${e.path}\n${e.before ?? '(new file)'}\n+++ ${e.path}\n${e.after}`)
-                    .join('\n\n')
-                : `Runs as ${this.tools.mode === 'tools-user' ? `tools user ${this.tools.user} (uid ${this.tools.uid})` : 'your local user'}, ${this.sandboxText()}\nDirectory: ${root}\nTimeout: ${args.timeout_ms} ms\nCommand:\n${args.command}`;
+                ? reviewLocalEdits(args.edits)
+                : `Runs as ${this.tools.mode === 'tools-user' ? `tools user ${this.tools.user} (uid ${this.tools.uid})` : 'your local user'}, ${this.sandboxText(this.bound(args), !!args.outside_sandbox)}\nDirectory: ${root}${args.background ? `\nRuns in the background until stopped (at most ${BACKGROUND_LIFETIME / 3600000} h); the last ${TASK_TAIL / 1024} KiB of output is kept` : `\nTimeout: ${args.timeout_ms} ms`}\n${danger.dangerous ? `Dangerous (${danger.category}): ${danger.reason}\n` : ''}${publishes ? `Publishes: ${publishes}; this always asks, except in YOLO\n` : ''}${args.outside_sandbox ? `Outside the sandbox: ${args.outside_sandbox}. This one command runs without the OS sandbox; the session stays sandboxed. This always asks, except in YOLO or your own rule\n` : ''}${args.listen ? 'May listen: this command may accept network connections. macOS cannot limit listening to localhost, so a server bound to 0.0.0.0 is reachable from your network. This always asks, except in YOLO or your own rule\n' : ''}Command:\n${args.command}`;
             const permission = this.managed.prepareWorkspaceInTransaction(session, epoch, attempt, toolCall, `Local ${kind}: ${root}`, reviewed, digest({ root, args }));
             c.operation_id = permission.operation.id;
             this.store.db
@@ -189,9 +319,73 @@ export class LocalCoding {
                 action: kind,
             });
         });
+        if (review)
+            this.store.transaction(() => this.store.event(session, 'permission.classifier', {
+                call_id: c.id,
+                operation_id: c.operation_id,
+                model: review.model,
+                verdict: review.verdict,
+                escalated,
+                ...(review.reason ? { reason: review.reason } : {}),
+            }));
         const policy = permissionPolicy(this.store, session);
-        if (args.action === 'edit' &&
-            matchesEditScope(policy, args.edits.map((e) => e.path))) {
+        // Desk-session rules: a matching deny refuses, a matching allow approves and is recorded with the
+        // rule that decided it; anything else falls through to the scoped-edit policy and then asks.
+        if (this.rules && policy.mode !== 'inspect' && this.rules.applies(session)) {
+            const request = args.action === 'command'
+                ? { tool: 'command', argv: commandArgv(args.command) }
+                : { tool: 'edit', paths: args.edits.map((e) => e.path) };
+            // A repo's allow rules cannot approve a dangerous or publishing command: only the person's own
+            // rules can.
+            const usable = (all) => danger.dangerous ||
+                publishes ||
+                (args.action === 'command' && (args.listen || args.outside_sandbox))
+                ? all.filter((r) => !(r.source === 'repo' && r.effect === 'allow'))
+                : all;
+            const decided = evaluateRules(usable(this.rules.list(session)), request);
+            const approval = this.managed.forOperation(c.operation_id);
+            const rule = decided.rule && {
+                id: decided.rule.id,
+                source: decided.rule.source,
+                effect: decided.rule.effect,
+                tool: decided.rule.tool,
+                ...(decided.rule.command ? { command: decided.rule.command } : {}),
+                ...(decided.rule.paths ? { paths: decided.rule.paths } : {}),
+            };
+            if (decided.effect === 'deny' && rule) {
+                this.managed.decide(approval.id, 'rule-deny:' + c.id, approval.revision, approval.operation_digest, 'deny');
+                this.store.transaction(() => this.store.event(session, 'permission.rule-denied', {
+                    rule,
+                    call_id: c.id,
+                    operation_id: c.operation_id,
+                }));
+            }
+            else if (decided.effect === 'allow' && rule) {
+                const rules = this.rules;
+                this.managed.decide(approval.id, 'rule:' + c.id, approval.revision, approval.operation_digest, 'approve', {
+                    receipt: {
+                        policy_digest: permissionDigest(policy),
+                        policy_revision: policy.revision,
+                        rule,
+                        root,
+                        call_id: c.id,
+                    },
+                    decidedBy: 'rule:' + rule.source,
+                    authorize: () => {
+                        this.guard(c);
+                        const again = evaluateRules(usable(rules.list(session)), request);
+                        if (again.effect !== 'allow' || again.rule?.id !== rule.id)
+                            throw new ServiceError('permission_changed', 'Approval rules changed');
+                    },
+                });
+            }
+        }
+        // The session's mode approves by itself only what it covers (Phase 2b): scoped or ordinary
+        // project edits, and, in auto, commands that stay inside the OS sandbox. Re-checked at decision.
+        const covered = (p) => args.action === 'edit'
+            ? autoApprovesEdits(p, args.edits.map((e) => e.path))
+            : autoApprovesCommands(p, this.sandboxed(this.bound(args)), danger.dangerous, publishes !== null || args.listen === true || !!args.outside_sandbox) && !(escalated && p.access !== 'yolo');
+        if (this.managed.forOperation(c.operation_id).state === 'pending' && covered(policy)) {
             const approval = this.managed.forOperation(c.operation_id);
             this.managed.decide(approval.id, 'scoped:' + c.id, approval.revision, approval.operation_digest, 'approve', {
                 receipt: {
@@ -203,13 +397,25 @@ export class LocalCoding {
                 authorize: () => {
                     this.guard(c);
                     const fresh = permissionPolicy(this.store, session);
-                    if (permissionDigest(fresh) !== permissionDigest(policy) ||
-                        args.action !== 'edit' ||
-                        !matchesEditScope(fresh, args.edits.map((e) => e.path)))
+                    if (permissionDigest(fresh) !== permissionDigest(policy) || !covered(fresh))
                         throw new ServiceError('permission_changed', 'Scoped edit policy changed');
-                    verifyLocalEdits(root, args.edits);
+                    if (args.action === 'edit')
+                        verifyLocalEdits(root, args.edits);
                 },
             });
+            // YOLO approves everything; each approval is recorded with what full access would have asked.
+            if (policy.access === 'yolo')
+                this.store.transaction(() => this.store.event(session, 'permission.yolo-approved', {
+                    call_id: c.id,
+                    operation_id: c.operation_id,
+                    action: args.action,
+                    ...(args.action === 'command' ? { command: args.command } : {}),
+                    ...(danger.dangerous
+                        ? { would_have_asked: { category: danger.category, reason: danger.reason } }
+                        : publishes
+                            ? { would_have_asked: { category: 'publish', reason: publishes } }
+                            : {}),
+                }));
         }
         return this.view(c.id);
     }
@@ -278,44 +484,154 @@ export class LocalCoding {
                 });
             }
         }
+        else if (args.background === true)
+            this.background(c, String(args.command), this.bound(args));
         else
-            this.command(c, String(args.command), Number(args.timeout_ms));
+            this.command(c, String(args.command), Number(args.timeout_ms), this.bound(args));
         return this.view(id);
     }
-    sandboxText() {
-        const { kind, level } = this.sandbox;
+    /** The sandbox for a new command in this session: the host's, or full access if the person chose
+     * it for this session (Phase 2b). Bound into the command's approval and digest. */
+    sandboxFor(session) {
+        return permissionPolicy(this.store, session).access
+            ? { ...this.sandbox, level: 'full-access' }
+            : this.sandbox;
+    }
+    /** The sandbox a prepared command was approved under. */
+    bound(args) {
+        return args.sandbox?.level === 'full-access'
+            ? { ...this.sandbox, level: 'full-access' }
+            : this.sandbox;
+    }
+    sandboxed(sb) {
+        return sb.kind !== 'none' && sb.level !== 'full-access';
+    }
+    /** Where this session's next command runs, in a word or two for the status and side panels. */
+    commandSandbox(session) {
+        const access = permissionPolicy(this.store, session).access;
+        if (access)
+            return access === 'yolo' ? 'YOLO' : 'full access';
+        if (this.sandbox.level === 'full-access')
+            return 'no sandbox';
+        if (this.sandbox.kind === 'none')
+            return this.sandbox.allowUnsandboxed ? 'no sandbox' : 'refused';
+        return this.sandbox.kind === 'seatbelt' ? 'Seatbelt' : 'bubblewrap';
+    }
+    sandboxText(sb = this.sandbox, outside = false) {
+        const { kind, level } = sb;
+        if (outside)
+            return 'unsandboxed for this one command, at its own request: it can read and change any file your user can and reach the network.';
         if (level === 'full-access')
-            return 'unsandboxed: the operator chose full access. May access files and network beyond this workspace.';
+            return this.sandbox.level === 'full-access'
+                ? 'unsandboxed: the operator chose full access. May access files and network beyond this workspace.'
+                : 'unsandboxed: you turned on full access for this session. May access files and network beyond this workspace.';
         if (kind === 'none')
             return 'unsandboxed: this host has no usable command sandbox, so the command may access files and network beyond this workspace.';
         const name = kind === 'seatbelt' ? 'Seatbelt' : 'bubblewrap';
-        const net = this.brokerNetwork()
+        const net = this.brokerNetwork(sb)
             ? 'network: through the broker allowlist (hosts set by the stk policy), nothing direct.'
             : 'has no network.';
+        const reads = this.sandbox.readPaths?.length
+            ? ` It can also read ${this.sandbox.readPaths.length} operator-allowed path${this.sandbox.readPaths.length === 1 ? '' : 's'} outside the workspace.`
+            : '';
         return level === 'read-only'
-            ? `in a ${name} sandbox (read-only): it can read this workspace but write nothing, and ${net}`
-            : `in a ${name} sandbox (workspace-write): it can write only inside this workspace, and ${net}`;
+            ? `in a ${name} sandbox (read-only): it can read this workspace but write nothing, and ${net}${reads}`
+            : `in a ${name} sandbox (workspace-write): it can write only inside this workspace, and ${net}${reads}`;
     }
     /** Broker network applies only to a sandboxed command: unsandboxed ones are not confined anyway. */
-    brokerNetwork() {
-        return this.sandbox.network &&
-            this.sandbox.kind !== 'none' &&
-            this.sandbox.level !== 'full-access'
-            ? this.sandbox.network
-            : null;
+    brokerNetwork(sb = this.sandbox) {
+        return sb.network && this.sandboxed(sb) ? sb.network : null;
+    }
+    /** Run a hook (Phase 4b) as one of this session's sandboxed commands would run: the same sandbox
+     * and level, no network, a minimal environment, `input` on stdin, bounded output and a timeout.
+     * Never as the tools user, whose process accounting is for approved operations only. */
+    runHook(session, command, input, timeoutMs) {
+        const refused = (why) => Promise.resolve({
+            code: null,
+            stdout: '',
+            stderr: '',
+            timedOut: false,
+            truncated: false,
+            refused: why,
+        });
+        if (this.tools.mode === 'tools-user')
+            return refused('Hooks do not run when commands run as a separate tools user');
+        const sb = this.sandboxFor(session);
+        if (sb.kind === 'bwrap' && sb.level !== 'full-access' && !sb.bwrap)
+            return refused('This host has no usable bubblewrap, so it cannot run a sandboxed hook');
+        if (sb.kind === 'none' && sb.level !== 'full-access' && !sb.allowUnsandboxed)
+            return refused(UNSANDBOXED_REFUSAL);
+        const root = this.store.session(session).cwd;
+        const tmp = sb.kind === 'seatbelt' && sb.level !== 'full-access'
+            ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-hook-')))
+            : undefined;
+        const argv = this.commandArgv(root, command, tmp, null, sb);
+        const cap = 16 * 1024;
+        return new Promise((resolve) => {
+            let stdout = '', stderr = '', truncated = false, timedOut = false;
+            const child = spawn(argv[0], argv.slice(1), {
+                cwd: root,
+                detached: true,
+                env: {
+                    PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin',
+                    HOME: process.env.HOME ?? root,
+                    LANG: 'en_US.UTF-8',
+                    TMPDIR: '/tmp',
+                    SALAAM_PROJECT_DIR: root,
+                    CLAUDE_PROJECT_DIR: root,
+                },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const take = (current, chunk) => {
+                const room = cap - Buffer.byteLength(current);
+                if (chunk.length > room)
+                    truncated = true;
+                return room > 0 ? current + chunk.subarray(0, room).toString('utf8') : current;
+            };
+            child.stdout.on('data', (c) => (stdout = take(stdout, c)));
+            child.stderr.on('data', (c) => (stderr = take(stderr, c)));
+            child.stdin.on('error', () => { });
+            child.stdin.end(input);
+            const timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            }, timeoutMs);
+            const finish = (code) => {
+                clearTimeout(timer);
+                if (tmp)
+                    rmSync(tmp, { recursive: true, force: true });
+                resolve({ code: timedOut ? null : code, stdout, stderr, timedOut, truncated });
+            };
+            child.once('error', (error) => {
+                stderr = take(stderr, Buffer.from(error.message));
+                finish(null);
+            });
+            child.once('close', (code) => finish(code));
+        });
     }
     /** The process a command runs as. Under the tools user, the host-side shell reports its own
      * process group (the one a stop kills) before exec-ing bubblewrap, whose PID namespace would
      * otherwise report a number that means nothing on the host. */
-    commandArgv(root, script, tmp, relay) {
-        const sandboxed = this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access';
+    commandArgv(root, script, tmp, relay, sb = this.sandbox, listen = false) {
+        const sandboxed = this.sandboxed(sb);
         const inner = (s) => !sandboxed
             ? ['/bin/sh', '-c', s]
-            : this.sandbox.kind === 'seatbelt'
-                ? seatbeltArgv(this.sandbox.level, root, tmp ?? '', ['/bin/sh', '-c', s], this.sandbox.seatbelt ?? null, { network: false, ...(relay?.port ? { brokerPort: relay.port } : {}) })
-                : sandboxArgv(this.sandbox.level, root, ['/bin/sh', '-c', s], this.sandbox.bwrap, {
+            : sb.kind === 'seatbelt'
+                ? seatbeltArgv(sb.level, root, tmp ?? '', ['/bin/sh', '-c', s], sb.seatbelt ?? null, {
+                    network: false,
+                    ...(relay?.port ? { brokerPort: relay.port } : {}),
+                    readPaths: sb.readPaths ?? [],
+                    ...(listen ? { listen: true } : {}),
+                })
+                : sandboxArgv(sb.level, root, ['/bin/sh', '-c', s], sb.bwrap, {
                     network: false,
                     ...(relay?.dir ? { broker: { dir: relay.dir, node: process.execPath } } : {}),
+                    readPaths: sb.readPaths ?? [],
                 });
         if (this.tools.mode !== 'tools-user')
             return inner(script);
@@ -332,11 +648,11 @@ export class LocalCoding {
             ])
             : toolArgv(this.tools, ['/usr/bin/setsid', '-w', '/bin/sh', '-c', marker + script]);
     }
-    command(c, command, timeout) {
-        const broker = this.brokerNetwork();
+    command(c, command, timeout, sb) {
+        const broker = this.brokerNetwork(sb);
         // The relay is Salaam's, outside the sandbox: it forwards to stk and counts what was reached.
         const relayStarting = broker
-            ? BrokerRelay.start(broker.socket, this.sandbox.kind === 'seatbelt' ? 'tcp' : 'unix')
+            ? BrokerRelay.start(broker.socket, sb.kind === 'seatbelt' ? 'tcp' : 'unix')
             : Promise.resolve(null);
         // A stop that arrives while the relay starts still cancels the command once it is spawned.
         let early = false;
@@ -344,7 +660,7 @@ export class LocalCoding {
             early = true;
         };
         // Seatbelt has no tmpfs: each command gets its own private tmp, removed when it ends.
-        const tmp = this.sandbox.kind === 'seatbelt' && this.sandbox.level !== 'full-access'
+        const tmp = sb.kind === 'seatbelt' && sb.level !== 'full-access'
             ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-cmd-')))
             : undefined;
         const set = (s) => {
@@ -352,12 +668,12 @@ export class LocalCoding {
             if (early)
                 s();
         };
-        const done = relayStarting.then((relay) => this.runCommand(c, command, timeout, tmp, relay, set), () => this.runCommand(c, command, timeout, tmp, null, set, !!broker));
+        const done = relayStarting.then((relay) => this.runCommand(c, command, timeout, tmp, relay, set, false, sb), () => this.runCommand(c, command, timeout, tmp, null, set, !!broker, sb));
         this.jobs.set(c.id, { stop: () => stop(), done });
         if (tmp)
             void done.finally(() => rmSync(tmp, { recursive: true, force: true }));
     }
-    runCommand(c, command, timeout, tmp, relay, setStop, relayFailed = false) {
+    runCommand(c, command, timeout, tmp, relay, setStop, relayFailed = false, sb = this.sandbox) {
         let stop = () => { };
         return new Promise((resolve) => {
             let output = '', bytes = 0, reason = null, finished = false;
@@ -366,7 +682,7 @@ export class LocalCoding {
             const tools = this.tools.mode === 'tools-user';
             const script = 'IFS= read -r salaam_start_gate || exit 125\nexec 0</dev/null\n' + command;
             // As the tools user, setsid makes the shell its own group leader so it can be killed by group.
-            const argv = this.commandArgv(c.root, script, tmp, relay);
+            const argv = this.commandArgv(c.root, script, tmp, relay, sb, JSON.parse(c.args).listen === true);
             let toolGroup = null, marker = tools ? '' : null, spawned = false;
             // Release the gate only once the process is owned and, as the tools user, its group is
             // known: otherwise a kill before the marker could miss a command already running.
@@ -382,6 +698,7 @@ export class LocalCoding {
                     HOME: process.env.HOME ?? c.root,
                     LANG: 'en_US.UTF-8',
                     TMPDIR: '/tmp',
+                    ...(this.sandboxed(sb) ? gitIdentityEnv(c.root) : {}),
                     ...(relay ? proxyEnv(relay.port ?? COMMAND_NETWORK_PORT) : {}),
                 },
                 stdio: ['pipe', 'pipe', 'pipe'],
@@ -532,12 +849,8 @@ export class LocalCoding {
                     state,
                     error: error ? 'Command could not start' : null,
                     isolation: (tools ? 'tools-user-' : 'local-user-') +
-                        (this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
-                            ? this.sandbox.kind + '-' + this.sandbox.level
-                            : 'no-os-sandbox'),
-                    sandbox: this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
-                        ? this.sandbox.kind
-                        : 'none',
+                        (this.sandboxed(sb) ? sb.kind + '-' + sb.level : 'no-os-sandbox'),
+                    sandbox: this.sandboxed(sb) ? sb.kind : 'none',
                     tool_uid: this.tools.uid,
                     ...(network ? { network } : {}),
                 };
@@ -554,12 +867,194 @@ export class LocalCoding {
             child.once('close', (code) => finish(code));
         });
     }
+    assertBackground(session) {
+        if (!this.interactive(session))
+            throw new ServiceError('background_denied', 'Background commands are only for an interactive local coding session');
+        if (this.tools.mode === 'tools-user')
+            throw new ServiceError('background_denied', 'Background commands do not yet run as a separate tools user');
+        if ([...this.live.values()].filter((t) => t.session === session).length >= TASK_LIMIT)
+            throw new ServiceError('background_limit', `A session runs at most ${TASK_LIMIT} background commands; stop one first`);
+    }
+    /** Launch an approved background command. Its operation settles once the process is owned;
+     * the process then lives as a session task until it exits, is stopped, or the session ends. */
+    background(c, command, sb) {
+        const settle = (ok, result) => this.store.transaction(() => {
+            this.change(c, ok ? 'succeeded' : 'failed', result);
+            this.managed.localExecutionResultInTransaction(c.operation_id, ok, result);
+        });
+        try {
+            this.assertBackground(c.session_id);
+        }
+        catch (error) {
+            settle(false, { error: error.message, background: true });
+            return;
+        }
+        const id = 'task_' + randomUUID().slice(0, 8);
+        const tmp = sb.kind === 'seatbelt' && sb.level !== 'full-access'
+            ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-cmd-')))
+            : undefined;
+        // Network for a long-lived task needs a relay that lives as long; keep it simple and honest.
+        const script = 'IFS= read -r salaam_start_gate || exit 125\nexec 0</dev/null\n' + command;
+        const argv = this.commandArgv(c.root, script, tmp, null, sb, JSON.parse(c.args).listen === true);
+        const child = spawn(argv[0], argv.slice(1), {
+            cwd: c.root,
+            detached: true,
+            env: {
+                PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin',
+                HOME: process.env.HOME ?? c.root,
+                LANG: 'en_US.UTF-8',
+                TMPDIR: '/tmp',
+                ...(this.sandboxed(sb) ? gitIdentityEnv(c.root) : {}),
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let tail = Buffer.alloc(0), bytes = 0, ended = null, resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const kill = () => {
+            if (child.pid)
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+        };
+        const task = {
+            id,
+            session: c.session_id,
+            done,
+            output: () => ({ output: tail.toString('utf8'), bytes, truncated: bytes > tail.length }),
+            stop: (why) => {
+                ended ??= why;
+                kill();
+            },
+        };
+        const collect = (chunk) => {
+            bytes += chunk.length;
+            tail = Buffer.concat([tail, chunk]);
+            if (tail.length > TASK_TAIL)
+                tail = tail.subarray(tail.length - TASK_TAIL);
+        };
+        child.stdout.on('data', collect);
+        child.stderr.on('data', collect);
+        child.stdin.on('error', () => { });
+        const lifetime = setTimeout(() => task.stop('timed_out'), BACKGROUND_LIFETIME);
+        // The session, not the turn, owns the task: it ends when local coding or its root goes away.
+        const watch = setInterval(() => {
+            try {
+                if (this.closed || !this.store.localCoding(c.session_id))
+                    throw Error('closed');
+                if (this.store.session(c.session_id).cwd !== c.root)
+                    throw Error('moved');
+            }
+            catch {
+                task.stop('stopped');
+            }
+        }, 1000);
+        const finish = (code) => {
+            clearTimeout(lifetime);
+            clearInterval(watch);
+            kill();
+            this.live.delete(id);
+            this.kept.set(id, task.output());
+            if (this.kept.size > 32)
+                this.kept.delete(this.kept.keys().next().value);
+            if (tmp)
+                rmSync(tmp, { recursive: true, force: true });
+            const row = this.store.db.prepare('SELECT * FROM local_tasks WHERE id=?').get(id);
+            if (row)
+                this.endTask(row, ended ?? 'exited', code);
+            else
+                settle(false, { error: 'Command could not start', background: true });
+            resolve();
+        };
+        child.once('error', () => finish(null));
+        child.once('close', (code) => finish(code));
+        child.once('spawn', () => {
+            try {
+                // The start time, not processIdentity: the gated shell execs into the command.
+                const identity = processStart(child.pid);
+                if (!identity)
+                    throw Error('No process identity');
+                this.store.transaction(() => this.store.db
+                    .prepare("INSERT INTO local_tasks(id,session_id,call_id,command,state,pid,identity,started_at) VALUES (?,?,?,?,'running',?,?,?)")
+                    .run(id, c.session_id, c.id, command, child.pid, identity, new Date().toISOString()));
+                this.live.set(id, task);
+                settle(true, {
+                    background: true,
+                    task_id: id,
+                    state: 'running',
+                    isolation: 'local-user-' + (this.sandboxed(sb) ? sb.kind + '-' + sb.level : 'no-os-sandbox'),
+                    sandbox: this.sandboxed(sb) ? sb.kind : 'none',
+                    note: 'Read its output with salaam_tasks; it keeps running after this turn.',
+                });
+                child.stdin.end('start\n');
+            }
+            catch {
+                ended = 'lost';
+                kill();
+            }
+        });
+    }
+    endTask(t, state, code) {
+        this.store.transaction(() => {
+            this.store.db
+                .prepare("UPDATE local_tasks SET state=?,exit_code=?,ended_at=? WHERE id=? AND state='running'")
+                .run(state, code, new Date().toISOString(), t.id);
+            this.store.event(t.session_id, 'local.task_finished', {
+                task_id: t.id,
+                command: t.command.slice(0, 200),
+                state,
+                exit_code: code,
+            });
+        });
+    }
+    /** The session's background tasks, newest first. */
+    tasks(session) {
+        return this.store.db
+            .prepare('SELECT * FROM local_tasks WHERE session_id=? ORDER BY started_at DESC, rowid DESC')
+            .all(session).map((t) => ({
+            id: t.id,
+            command: t.command,
+            state: t.state,
+            exit_code: t.exit_code,
+            pid: t.pid,
+            started_at: t.started_at,
+            ended_at: t.ended_at,
+            bytes: this.live.get(t.id)?.output().bytes ?? null,
+        }));
+    }
+    task(session, id) {
+        const row = this.store.db
+            .prepare('SELECT * FROM local_tasks WHERE id=? AND session_id=?')
+            .get(id, session);
+        if (!row)
+            throw new ServiceError('not_found', 'No such background task in this session', 404);
+        return row;
+    }
+    /** The kept tail of a task's output. Output of a task this controller no longer owns is gone. */
+    taskOutput(session, id) {
+        const row = this.task(session, id);
+        const live = this.live.get(id);
+        return {
+            task: { id: row.id, state: row.state, exit_code: row.exit_code },
+            ...(live?.output() ?? this.kept.get(id) ?? { output: '', bytes: 0, truncated: false }),
+        };
+    }
+    stopTask(session, id) {
+        this.task(session, id);
+        this.live.get(id)?.stop('stopped');
+        return { stopping: this.live.has(id) };
+    }
     async close() {
         this.closed = true;
         const jobs = [...this.jobs.values()];
         for (const job of jobs)
             job.stop();
-        await Promise.all(jobs.map((j) => j.done));
+        const tasks = [...this.live.values()];
+        for (const t of tasks)
+            t.stop('stopped');
+        await Promise.all([...jobs.map((j) => j.done), ...tasks.map((t) => t.done)]);
         this.unregister();
     }
 }