mtech-ai-local-runner 0.1.46 → 0.1.48

package/README.md

@@ -1,3 +1,105 @@
+## Unreleased: AI-first ask delivery and messenger mode (disabled)
+
+The runner can put an AI Gateway ask (a Work Decision, a named review or a work request), and the answer to it,
+into the employee's own running Claude Code or Codex session before any Slack message is sent (Work Item e1c08b33,
+owner Work Decision 266f9475, option A). Deliveries arrive as ids only on the existing session-open wait. The daemon
+keeps them in `asks.json` (mode 0600) and reports `received`, `shown`, `seen` or `dropped` with
+`local_agent_ask_delivery_report`; the runner sends the Gateway no session id, cwd, prompt or text. Hooks reach the
+daemon through `hub.sock` (0600, in the 0700 state root) and the stable shim `bin/gateway-hook`, which runs a small
+hook client that prints nothing unless the daemon answers within 300 ms.
+
+Only a session that a person is attending is served. A Claude Code session counts when `CLAUDE_CODE_SESSION_ATTENDED`
+is `1` or, where Claude Code does not export that variable, when `CLAUDE_CODE_ENTRYPOINT` names a terminal, the Claude
+desktop app or the VS Code extension. A headless `claude -p` or Agent SDK run gets nothing and is never counted as
+having seen an ask. Codex exports no such marker, so every Codex hook session counts. The runner's own jobs never
+count: a hook whose `HOME` is under `<stateRoot>/claude-jobs/` (where every Claude job runs) is refused, and Codex jobs
+run with `features.hooks=false`, so they run no hook at all.
+
+An ask is shown at a session start, at the next prompt (where it also counts as seen), at a turn end, or by waking an
+idle Claude session through an `asyncRewake` Stop watcher. An ask shown at a session start, at a turn end or by a wake
+counts as seen at the next prompt in that same session. A session is woken only within 30 minutes of a human prompt,
+and at most 6 times an hour. With no such session the ask becomes one macOS notification, which gives up after 3
+seconds and logs only an error code, and the ask waits for the next session start or prompt. Hook text is fixed and
+carries validated ids only; the AI reads the ask itself with the Gateway show tools, which mark its text as untrusted.
+
+The Gateway sends the ask keys on the wait only while asks are on for this runner. When a wait result comes without
+them, every stored delivery ends: it is dropped from `asks.json` with no report, and the Gateway's Slack fallback
+covers it. A stored delivery is forgotten an hour after it arrived, by which time the fallback (at most 15 minutes) has
+long run.
+
+Integrations are installed only on request, with `setup --integrations` or `integrations install`; setup never asks
+about them. An app already installed in the directory the environment names is skipped and reported installed, without
+rewriting its files:
+
+```bash
+npx mtech-ai-local-runner setup --integrations claude,codex
+npx mtech-ai-local-runner integrations status
+npx mtech-ai-local-runner integrations install codex
+npx mtech-ai-local-runner integrations remove claude
+```
+
+Claude Code gets the skills-directory plugin `~/.claude/skills/mtec-ai-gateway-asks/`, which loads as
+`mtec-ai-gateway-asks@skills-dir` in a new session or after `/reload-plugins`; `settings.json` is not touched. Codex gets
+four handlers appended to `~/.codex/hooks.json` after a backup of that file; trust them once with `/hooks`. A
+`hooks.json` that is not valid JSON, or whose hooks do not have the shape Codex reads, is left as it is and the install
+reports `CODEX_HOOKS_JSON_INVALID`. `uninstall` removes both integrations, the shim, `asks.json` and any temporary
+`asks.json.*.tmp` file a crash left behind, and it also works on a setup that never finished.
+
+`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honoured. The LaunchAgent that runs the daemon gets only `PATH`, so every
+install adds the directory it used to a list per app in `integrations.json` in the state root, and the daemon,
+`doctor`, `integrations remove` and `uninstall` look in every recorded directory as well as in the environment. A
+directory leaves the list only when nothing of the runner's is left in it, so installing into a second directory never
+orphans the first, and the shim stays while any directory still has the hooks. When no absolute home directory can be
+found, the command reports `INTEGRATION_HOME_UNKNOWN` for that app and writes nothing; set `HOME`, or `CLAUDE_CONFIG_DIR`
+and `CODEX_HOME`.
+
+On a fresh Mac without an admitted executor, or one already set up as a messenger, `setup` now completes in messenger
+mode. It registers with no adapter capability and stores `mode: "messenger"` in `config.json`. The daemon then runs only
+the session-open loop, for session opens and asks, and sends its own heartbeat at start, every 600 seconds and whenever
+the installed integrations change. It has no jobs loop, no adapter probe and no PreToolUse self-test, and `manual-codex`
+and `publication-recover` are refused with `MESSENGER_MODE_HAS_NO_EXECUTOR`. A full runner works as before and now
+reports `mode: "full"` in its heartbeat. `doctor` reports the mode, the hub and each integration, including whether
+Claude Code loads the plugin; for a messenger it requires neither an adapter nor the PreToolUse self-test.
+
+Setup never turns a Mac set up as a full runner into a messenger. With no usable adapter it fails as 0.1.47 did, before
+the login, and leaves `config.json`, the registration and the LaunchAgent as they were. Fix the adapter, or run
+`uninstall` and then `setup` to set the Mac up as a messenger.
+
+No ask is delivered until the Gateway's `AI_OPS_GATEWAY_WORK_ASK_AI_FIRST_ENABLED` switch is on and the employee is on
+its pilot list. Until then an existing runner works as before: setup never turns a full runner into a messenger and
+installs no integration it was not asked for. The one change without the switch is that setup on a fresh Mac without an
+admitted executor completes as a messenger instead of failing. Deploy the Gateway receivers before upgrading a runner.
+
+## 0.1.48: local_edit takes the complete file, not a patch
+
+Read the existing file first, then pass its complete desired new contents in
+`local_edit.content`, including unchanged text. The operation replaces the whole
+file or creates it; it never applies a diff. Recognizable apply_patch directives,
+unified hunk lines and diff headers return `DENIED_PATCH_CONTENT` before a write.
+The isolated writer enforces the same guard. Literal patch blocks in a document
+are also rejected by this conservative API; ordinary source string literals and
+YAML separators remain accepted. No partial old/new edit tool is introduced.
+
+Gateway and Runner must agree on the new tool inventory hash. Package runtime
+receipts change, while the reviewed Codex CLI release manifest identity stays
+unchanged. Keep existing -2G allowed paths; deploy the matching Gateway registry
+and exact runtime pins before switching a daemon. The candidate contains the
+newer development ask/messenger code documented in the Unreleased section and
+the 0.1.46/0.1.47 fixes; no integration is installed merely by preparing it.
+
+## 0.1.47: Claude security host wiring remains gated
+
+Claude now shares the job security session and checks a live opaque executable
+identity before launch. Account/control overlaps and aliases fail before control
+creation; preparation failure and cancellation revoke authority. A trusted
+host/probe/identity tuple is an in-process composition seam, not an environment
+switch or a receipt loaded from disk. Fake-data tests do not enable production:
+exact-release/native-policy, managed-input and credential/IPC/network evidence
+and production verifier registration remain outstanding. Existing login, settings
+and executable path are preserved. This release neither upgrades nor starts an
+installed daemon. See `docs/ai-ops-gateway/claude-execution-admission-remaining.md`
+in the Gateway repository for the consolidated verification boundary.
+
 ## 0.1.46: login and execution are separate
 
 A locally logged-in account may still be blocked by security admission. New
@@ -283,8 +385,11 @@ npx mtech-ai-local-runner setup
 The package stores safe runner configuration locally and keeps OAuth refresh credentials in macOS Keychain when available.
 
 Public npm installation requires no npm account or publishing OTP. Setup requires
-the employee's own Gateway OAuth login and a supported, authenticated selected
-CLI. Codex uses the employee's ChatGPT account. Claude requires its own login
+the employee's own Gateway OAuth login and, for a full runner, a supported,
+authenticated selected CLI. Since the AI-first ask delivery release (Unreleased,
+above), a fresh Mac without an admitted executor is set up as a messenger
+instead; a Mac already set up as a full runner still fails setup without one.
+Codex uses the employee's ChatGPT account. Claude requires its own login
 and a separately verified host admission; it is currently not admitted.
 
 For the current unattended Codex pilot, an administrator must separately install

package/dist/src/adapters/claude-code/adapter.js

@@ -74,45 +74,49 @@ export class ClaudeCodeAdapter {
             throw new Error("adapter has already been started");
         this.started = true;
         this.p1 = ctx.approvedTaskPackage?.verification?.mode === 'runner_observed_v1';
-        const generation = ctx.generation;
-        if (!Number.isSafeInteger(generation) || generation === undefined || generation < 1)
-            throw new Error("JOB_SECURITY_REJECTED");
-        const assertAdmission = () => {
-            const repositories = ctx.taskPackage?.repositories;
-            if (!Array.isArray(repositories) || repositories.length !== 1 || repositories[0]?.base_commit_sha !== this.options.securityPolicy?.pin.sourceSha)
-                throw new Error('JOB_SECURITY_REJECTED');
-            requireJobSecurity(this.options.securityPolicy, { adapterId: "claude_code_cli", adapterVersion: "1", jobId: this.options.jobId ?? ctx.bindingId, modelId: resolvedModelId, generation });
-            if (ctx.approvedTaskPackage?.resolved_provider !== "anthropic" || ctx.approvedTaskPackage?.resolved_model_id !== resolvedModelId
-                || ctx.approvedTaskPackage?.repository?.base_commit_sha !== this.options.securityPolicy.pin.sourceSha)
-                throw new Error("SECURITY_REQUIREMENTS_REJECTED");
-            requireSecurityRequirements(ctx.approvedTaskPackage?.security_requirements, { adapterId: "claude_code_cli", adapterVersion: "1", requirementsSha256: this.options.securityPolicy.pin.requirementsSha256 });
-        };
-        assertAdmission();
-        if (!ctx.securityBinding)
-            throw new Error('SECURITY_REQUIREMENTS_REJECTED');
-        this.receipt = createJobSecurityReceipt(this.options.securityPolicy, { jobId: this.options.jobId ?? ctx.bindingId, generation, modelId: resolvedModelId, sourceSha: this.options.securityPolicy.pin.sourceSha, ...ctx.securityBinding, requirements: ctx.approvedTaskPackage?.security_requirements });
-        const pkg = ctx.taskPackage;
-        const cwd = this.options.cwd;
-        const rel = cwd ? path.relative(path.resolve(this.options.worktreeRoot), path.resolve(cwd)) : "";
-        if (!cwd || !path.isAbsolute(cwd) || rel === "" || (!rel.startsWith(".." + path.sep) && rel !== ".." && !path.isAbsolute(rel)))
-            throw new Error("trusted cwd must live outside the assigned worktree");
-        const unbounded = isUnboundedLocalExecution(ctx.taskPackage);
-        if (!unbounded && (!Number.isFinite(this.options.maxBudgetUsd) || this.options.maxBudgetUsd <= 0)) {
-            throw new Error("refusing to start: no positive remaining contract budget was supplied");
-        }
-        if (!this.options.worktreeRoot) {
-            throw new Error("refusing to start: no assigned worktree was supplied");
-        }
-        if (!ctx.sessionId) {
-            throw new Error("refusing to start: no runner-generated session ID was supplied");
-        }
-        const hookCommand = this.requireTrustedHookCommand();
-        const prompt = compilePrompt(ctx.taskPackage, { workItemLabel: this.options.workItemLabel });
-        if (this.cancelled)
-            throw new Error('adapter startup cancelled');
         let acquired;
         this.startupAcquisition = new Promise(resolve => { acquired = resolve; });
         try {
+            const generation = ctx.generation;
+            if (!Number.isSafeInteger(generation) || generation === undefined || generation < 1)
+                throw new Error("JOB_SECURITY_REJECTED");
+            if (this.options.prepareSecurity)
+                await this.options.prepareSecurity(ctx);
+            if (this.cancelled)
+                throw new Error('adapter startup cancelled');
+            const assertAdmission = () => {
+                const repositories = ctx.taskPackage?.repositories;
+                if (!Array.isArray(repositories) || repositories.length !== 1 || repositories[0]?.base_commit_sha !== this.options.securityPolicy?.pin.sourceSha)
+                    throw new Error('JOB_SECURITY_REJECTED');
+                requireJobSecurity(this.options.securityPolicy, { adapterId: "claude_code_cli", adapterVersion: "1", jobId: this.options.jobId ?? ctx.bindingId, modelId: resolvedModelId, generation });
+                if (ctx.approvedTaskPackage?.resolved_provider !== "anthropic" || ctx.approvedTaskPackage?.resolved_model_id !== resolvedModelId
+                    || ctx.approvedTaskPackage?.repository?.base_commit_sha !== this.options.securityPolicy.pin.sourceSha)
+                    throw new Error("SECURITY_REQUIREMENTS_REJECTED");
+                requireSecurityRequirements(ctx.approvedTaskPackage?.security_requirements, { adapterId: "claude_code_cli", adapterVersion: "1", requirementsSha256: this.options.securityPolicy.pin.requirementsSha256 });
+            };
+            assertAdmission();
+            if (!ctx.securityBinding)
+                throw new Error('SECURITY_REQUIREMENTS_REJECTED');
+            this.receipt = createJobSecurityReceipt(this.options.securityPolicy, { jobId: this.options.jobId ?? ctx.bindingId, generation, modelId: resolvedModelId, sourceSha: this.options.securityPolicy.pin.sourceSha, ...ctx.securityBinding, requirements: ctx.approvedTaskPackage?.security_requirements });
+            const pkg = ctx.taskPackage;
+            const cwd = this.options.cwd;
+            const rel = cwd ? path.relative(path.resolve(this.options.worktreeRoot), path.resolve(cwd)) : "";
+            if (!cwd || !path.isAbsolute(cwd) || rel === "" || (!rel.startsWith(".." + path.sep) && rel !== ".." && !path.isAbsolute(rel)))
+                throw new Error("trusted cwd must live outside the assigned worktree");
+            const unbounded = isUnboundedLocalExecution(ctx.taskPackage);
+            if (!unbounded && (!Number.isFinite(this.options.maxBudgetUsd) || this.options.maxBudgetUsd <= 0)) {
+                throw new Error("refusing to start: no positive remaining contract budget was supplied");
+            }
+            if (!this.options.worktreeRoot) {
+                throw new Error("refusing to start: no assigned worktree was supplied");
+            }
+            if (!ctx.sessionId) {
+                throw new Error("refusing to start: no runner-generated session ID was supplied");
+            }
+            const hookCommand = this.requireTrustedHookCommand();
+            const prompt = compilePrompt(ctx.taskPackage, { workItemLabel: this.options.workItemLabel });
+            if (this.cancelled)
+                throw new Error('adapter startup cancelled');
             if (!this.options.createTools || !this.options.writeLocalMcpConfig)
                 throw new Error("job-local tool setup is required");
             this.tools = await this.options.createTools(ctx, pkg, ctx.approvedTaskPackage ?? {});
@@ -166,6 +170,9 @@ export class ClaudeCodeAdapter {
                 ...allowlistedEnv(this.options.env),
                 [HOOK_POLICY_ENV_VAR]: encodeHookPolicy(hookPolicy),
             };
+            await this.options.assertCurrentInputs?.();
+            if (this.cancelled)
+                throw new Error('adapter startup cancelled');
             assertAdmission();
             const handle = this.options.processHost.spawn(this.options.binaryPath ?? "claude", args, {
                 cwd,
@@ -259,6 +266,7 @@ export class ClaudeCodeAdapter {
         if (this.cancelPromise)
             return this.cancelPromise;
         this.localReadObservations();
+        this.revokeSecurity();
         this.revokeTools(this.tools);
         const cleanup = (async () => { await this.startupAcquisition; await this.cleanup(); })();
         // This bounds cleanup confirmation, never admitted model runtime. Unknown
@@ -269,6 +277,18 @@ export class ClaudeCodeAdapter {
         });
         return this.cancelPromise;
     }
+    securityRevoked = false;
+    revokeSecurity() {
+        if (this.securityRevoked)
+            return;
+        this.securityRevoked = true;
+        try {
+            this.options.revokeSecurity?.();
+        }
+        catch {
+            this.revokeFailed = true;
+        }
+    }
     revokeTools(tools) {
         if (!tools || this.revokedTools === tools)
             return;
@@ -291,6 +311,7 @@ export class ClaudeCodeAdapter {
         this.tools = undefined;
         this.handle = null;
         const operation = Promise.resolve().then(async () => {
+            this.revokeSecurity();
             this.revokeTools(tools);
             let failed = this.revokeFailed;
             try {

package/dist/src/adapters/claude-code/runtime-options.js

@@ -1,15 +1,52 @@
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { mkdir, realpath, rm } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
+import { JobSecuritySession } from '../../safety/job-security-session.js';
+import { assertCurrentClaudeBinary, claudeBinaryLaunchPath } from '../../safety/claude-binary-identity.js';
 import { writeFileSync } from 'node:fs';
 import { NodeProcessGroupHost } from '../../process/node-process-group-host.js';
 import { JobToolSession } from '../../safety/job-tool-session.js';
 import { jobToolPolicyOptions } from '../../safety/job-tool-policy.js';
 import { requireJobSecurity } from '../../safety/job-security-policy.js';
 const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+/** Resolve the existing prefix without creating a path through an account alias. */
+async function canonicalFuture(file) {
+    let parent = file;
+    const tail = [];
+    for (;;) {
+        try {
+            await lstat(parent);
+            return path.join(await realpath(parent), ...tail);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const next = path.dirname(parent);
+            if (next === parent)
+                throw error;
+            tail.unshift(path.basename(parent));
+            parent = next;
+        }
+    }
+}
 /** Wiring only. No release verifier or admission certificate exists here. */
 export function createClaudeCodeAdapterOptions(input) {
+    if (input.securityHost && (input.securityPolicy || input.nativeBinding || input.commandRegistry) || !!input.securityHost !== !!input.binaryIdentity)
+        throw Error('CLAUDE_SECURITY_AUTHORITY_CONFLICT');
+    const security = new JobSecuritySession(input.securityHost);
+    let securityPolicy = input.securityPolicy, disposed = false;
     const checkout = path.resolve(input.worktreePath), state = path.resolve(input.stateRoot);
+    const account = input.env.CLAUDE_CONFIG_DIR ?? (input.env.HOME ? path.join(input.env.HOME, '.claude') : undefined);
+    if (account !== undefined && (!path.isAbsolute(account) || /[\r\n\0]/.test(account)))
+        throw Error('CLAUDE_ACCOUNT_CONTEXT_UNAVAILABLE');
+    const assertOutsideAccount = (storage, source, auth = account) => { if (auth && [storage, source].some(root => inside(path.resolve(auth), root) || inside(root, path.resolve(auth))))
+        throw Error('CLAUDE_ACCOUNT_CONTROL_OVERLAP'); };
+    assertOutsideAccount(state, checkout);
+    const revoke = () => { disposed = true; security.revoke(); securityPolicy?.revoke(); };
+    const binary = input.binaryIdentity ? claudeBinaryLaunchPath(input.binaryIdentity) : input.binaryPath;
+    if (input.binaryPath && binary !== input.binaryPath)
+        throw Error('CLAUDE_BINARY_IDENTITY_REJECTED');
     if (inside(checkout, state))
         throw new Error('Claude job controls must be outside the checkout');
     const control = path.join(state, 'claude-jobs', randomUUID());
@@ -22,47 +59,91 @@ export function createClaudeCodeAdapterOptions(input) {
     env.TMPDIR = path.join(control, 'tmp'); // Claude owns credential access. Preserve the account location by path only;
     // never read/copy its files or send this environment to scoped workers.
     // https://code.claude.com/docs/en/authentication#log-in-with-multiple-accounts
-    env.CLAUDE_CONFIG_DIR = input.env.CLAUDE_CONFIG_DIR ?? (input.env.HOME ? path.join(input.env.HOME, '.claude') : undefined);
+    env.CLAUDE_CONFIG_DIR = account;
     if (env.CLAUDE_CONFIG_DIR && !path.isAbsolute(env.CLAUDE_CONFIG_DIR))
         throw new Error('Claude account configuration path must be absolute');
     return {
-        processHost: new NodeProcessGroupHost(), worktreeRoot: checkout, jobId: input.jobId, securityPolicy: input.securityPolicy,
-        cwd, env, binaryPath: input.binaryPath, hookExecutablePath: input.hookExecutablePath, hookNodeExecutablePath: input.hookNodeExecutablePath,
+        processHost: new NodeProcessGroupHost(), worktreeRoot: checkout, jobId: input.jobId, get securityPolicy() { return securityPolicy; },
+        ...(input.securityHost ? { prepareSecurity: async (ctx) => {
+                try {
+                    if (disposed || !ctx.securityBinding || !account)
+                        throw Error('JOB_SECURITY_SESSION_REJECTED');
+                    const approved = ctx.approvedTaskPackage, repo = approved?.repository;
+                    securityPolicy = await security.authorize({ adapterId: 'claude_code_cli', adapterVersion: '1', jobId: input.jobId, generation: ctx.generation, modelId: ctx.resolvedModelId,
+                        sourceSha: String(repo?.base_commit_sha ?? ''), requirements: approved?.security_requirements, ...ctx.securityBinding });
+                    if (disposed)
+                        throw Error('JOB_SECURITY_SESSION_REJECTED');
+                    await assertCurrentClaudeBinary(input.binaryIdentity, binary, securityPolicy.pin.binarySha256);
+                    return securityPolicy;
+                }
+                catch (error) {
+                    revoke();
+                    throw error;
+                }
+            } } : {}),
+        revokeSecurity: revoke,
+        assertCurrentInputs: async () => { if (disposed)
+            throw Error('JOB_SECURITY_SESSION_REJECTED'); if (input.binaryIdentity) {
+            if (!securityPolicy)
+                throw Error('JOB_SECURITY_SESSION_REJECTED');
+            await assertCurrentClaudeBinary(input.binaryIdentity, binary, securityPolicy.pin.binarySha256);
+        } },
+        cwd, env, binaryPath: binary, hookExecutablePath: input.hookExecutablePath, hookNodeExecutablePath: input.hookNodeExecutablePath,
         maxBudgetUsd: input.maxBudgetUsd ?? 1, workItemLabel: input.workItemLabel ?? input.jobId,
         registeredReadTools: [], writeMcpConfig: () => { throw new Error('Gateway relay is not a model tool endpoint'); },
         createTools: async (ctx, pkg, approved) => {
-            await mkdir(state, { recursive: true, mode: 0o700 });
-            const realState = await realpath(state), realCheckout = await realpath(checkout);
-            if (realState !== state || inside(realCheckout, realState))
-                throw new Error('Claude job controls must be outside the checkout');
-            await mkdir(control, { recursive: true, mode: 0o700 });
-            for (const directory of [home, cwd, env.TMPDIR])
-                await mkdir(directory, { mode: 0o700 });
-            let active = true;
-            const tools = new JobToolSession({
-                policyOptions: jobToolPolicyOptions(checkout, pkg, approved, input.commandRegistry ?? [], { runtimeAdapter: 'claude_code_cli', runtimeAdapterVersion: '1' }),
-                binding: () => {
-                    const binding = input.nativeBinding?.();
-                    return binding && binding.jobId === input.jobId && binding.generation === input.securityPolicy?.pin.generation ? binding : null;
-                },
-                active: () => {
-                    if (!active)
-                        return false;
-                    try {
-                        requireJobSecurity(input.securityPolicy, { adapterId: 'claude_code_cli', adapterVersion: '1', jobId: input.jobId, modelId: ctx.resolvedModelId });
-                        return true;
+            if (disposed)
+                throw Error('JOB_SECURITY_SESSION_REJECTED');
+            const policyOptions = jobToolPolicyOptions(checkout, pkg, approved, input.securityHost ? security.commands() : input.commandRegistry ?? [], { runtimeAdapter: 'claude_code_cli', runtimeAdapterVersion: '1' });
+            const canonicalAccount = account ? await canonicalFuture(account) : undefined;
+            assertOutsideAccount(await canonicalFuture(state), await canonicalFuture(checkout), canonicalAccount);
+            assertOutsideAccount(await canonicalFuture(control), await canonicalFuture(checkout), canonicalAccount);
+            let owned = false;
+            try {
+                await mkdir(state, { recursive: true, mode: 0o700 });
+                const realState = await realpath(state), realCheckout = await realpath(checkout);
+                assertOutsideAccount(realState, realCheckout, account ? await canonicalFuture(account) : undefined);
+                if (realState !== state || inside(realCheckout, realState))
+                    throw new Error('Claude job controls must be outside the checkout');
+                await mkdir(path.dirname(control), { recursive: true, mode: 0o700 });
+                if (await realpath(path.dirname(control)) !== path.dirname(control))
+                    throw Error('CLAUDE_CONTROL_ALIAS_REJECTED');
+                await mkdir(control, { mode: 0o700 });
+                owned = true;
+                for (const directory of [home, cwd, env.TMPDIR])
+                    await mkdir(directory, { mode: 0o700 });
+                let active = true;
+                const tools = new JobToolSession({
+                    policyOptions,
+                    binding: () => {
+                        const binding = input.securityHost ? security.binding() : input.nativeBinding?.();
+                        return binding && binding.jobId === input.jobId && binding.generation === securityPolicy?.pin.generation ? binding : null;
+                    },
+                    active: () => {
+                        if (!active)
+                            return false;
+                        try {
+                            requireJobSecurity(securityPolicy, { adapterId: 'claude_code_cli', adapterVersion: '1', jobId: input.jobId, modelId: ctx.resolvedModelId, generation: ctx.generation, sourceSha: String(approved.repository.base_commit_sha) });
+                            return true;
+                        }
+                        catch {
+                            return false;
+                        }
+                    },
+                });
+                return { start: () => tools.start(), revoke: () => { active = false; tools.revoke(); }, close: async () => { active = false; revoke(); try {
+                        await tools.close();
                     }
-                    catch {
-                        return false;
-                    }
-                },
-            });
-            return { start: () => tools.start(), revoke: () => { active = false; tools.revoke(); }, close: async () => { active = false; try {
-                    await tools.close();
-                }
-                finally {
+                    finally {
+                        await rm(control, { recursive: true, force: true });
+                    } } };
+            }
+            catch (error) {
+                revoke();
+                if (owned)
                     await rm(control, { recursive: true, force: true });
-                } } };
+                throw error;
+            }
         },
         writeLocalMcpConfig: endpoint => {
             writeFileSync(config, JSON.stringify({ mcpServers: { ai_local: { type: 'http', url: endpoint.url, headers: { Authorization: `Bearer ${endpoint.token}` } } } }), { mode: 0o600, flag: 'wx' });

package/dist/src/asks/commands.js

@@ -0,0 +1,100 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ASKS_FILE } from "./store.js";
+import { installIntegration, integrationStatus, removeIntegration, removeShimIfUnused } from "./integrations.js";
+import { APPS, isApp } from "./types.js";
+const NEXT_STEP = {
+    claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-asks@skills-dir.",
+    codex: "Open Codex and trust the four AI Gateway hooks once with /hooks. Until then Codex skips them and the Slack message covers the gap.",
+};
+function errorCode(error) {
+    const code = error?.code;
+    if (typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code))
+        return code;
+    const message = error instanceof Error ? error.message.split(":")[0] : "";
+    return /^[A-Z0-9_]{1,64}$/.test(message) ? message : "INTEGRATION_FAILED";
+}
+/** integrations status|install|remove [claude|codex]; null for anything else. */
+export function parseIntegrationsArguments(argv) {
+    const [action, app, ...extra] = argv;
+    if (extra.length > 0 || (action !== "status" && action !== "install" && action !== "remove"))
+        return null;
+    if (app !== undefined && !isApp(app))
+        return null;
+    return { action, apps: app === undefined ? [...APPS] : [app] };
+}
+/** setup --integrations claude,codex (or --integrations=claude): undefined when absent, null when malformed. */
+export function parseSetupIntegrations(argv) {
+    const index = argv.findIndex(arg => arg === "--integrations" || arg.startsWith("--integrations="));
+    if (index < 0)
+        return undefined;
+    const value = argv[index] === "--integrations" ? argv[index + 1] : argv[index].slice("--integrations=".length);
+    const apps = (value ?? "").split(",").map(app => app.trim()).filter(app => app !== "");
+    if (apps.length === 0 || !apps.every(isApp) || new Set(apps).size !== apps.length)
+        return null;
+    return apps;
+}
+/** The state of one app; a status that cannot be read (no home directory, say) is reported with its error, never thrown. */
+export async function statusOf(app, env, stateRoot, error) {
+    try {
+        return { ...await integrationStatus(app, env, stateRoot), ...(error === undefined ? {} : { error }) };
+    }
+    catch (failure) {
+        return { app, state: "unreadable", path: "", error: error ?? errorCode(failure) };
+    }
+}
+async function attempt(app, env, stateRoot, change) {
+    try {
+        return await change();
+    }
+    catch (error) {
+        return statusOf(app, env, stateRoot, errorCode(error));
+    }
+}
+export async function installIntegrations(apps, env, stateRoot) {
+    const results = [];
+    for (const app of apps) {
+        const result = await attempt(app, env, stateRoot, () => installIntegration(app, env, stateRoot));
+        results.push(result.error === undefined ? { ...result, action: NEXT_STEP[app] } : result);
+    }
+    return results;
+}
+/**
+ * uninstall: removes both integrations, then the shim once nothing uses it, asks.json and the store's temporary files
+ * that a crash left behind (asks.json.<pid>.<uuid>.tmp), which can hold raw session ids.
+ */
+export async function removeAsksInstall(env, stateRoot) {
+    const results = [];
+    for (const app of APPS)
+        results.push(await attempt(app, env, stateRoot, () => removeIntegration(app, env, stateRoot)));
+    // A hook left behind (an unreadable Codex hooks file) keeps its shim, which then prints nothing and exits 0.
+    await removeShimIfUnused(env, stateRoot).catch(() => false);
+    await rm(join(stateRoot, ASKS_FILE), { force: true });
+    for (const name of await readdir(stateRoot).catch(() => [])) {
+        if (name.startsWith(`${ASKS_FILE}.`) && name.endsWith(".tmp"))
+            await rm(join(stateRoot, name), { force: true });
+    }
+    return results;
+}
+export async function runIntegrationsCommand(argv, io) {
+    const parsed = parseIntegrationsArguments(argv);
+    if (parsed === null) {
+        io.stderr("Usage: mtec-ai-local-runner integrations status|install|remove [claude|codex]");
+        return 1;
+    }
+    let results;
+    if (parsed.action === "install") {
+        results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+    }
+    else if (parsed.action === "remove") {
+        results = [];
+        for (const app of parsed.apps)
+            results.push(await attempt(app, io.env, io.stateRoot, () => removeIntegration(app, io.env, io.stateRoot)));
+        await removeShimIfUnused(io.env, io.stateRoot).catch(() => false);
+    }
+    else {
+        results = await Promise.all(parsed.apps.map(app => statusOf(app, io.env, io.stateRoot)));
+    }
+    io.stdout(JSON.stringify({ integrations: results }));
+    return results.some(result => result.error !== undefined) ? 1 : 0;
+}

package/dist/src/asks/doctor.js

@@ -0,0 +1,106 @@
+import { execFile } from "node:child_process";
+import { connect } from "node:net";
+import { statusOf } from "./commands.js";
+import { hubSocketPath } from "./hub.js";
+import { MAX_LINE_BYTES, encodeLine } from "./hub-protocol.js";
+import { CLAUDE_PLUGIN_NAME } from "./integrations.js";
+import { APPS } from "./types.js";
+const PLUGIN_ID = `${CLAUDE_PLUGIN_NAME}@skills-dir`;
+const CLAUDE_NOT_LOADED = `Claude Code does not load ${PLUGIN_ID}. Managed settings can block skills-directory plugins `
+    + "(strictPluginOnlyCustomization, a strictKnownMarketplaces list without the skills-dir source, or blockedMarketplaces): "
+    + "ask your administrator, or install the plugin from a directory marketplace your organization allows (claude plugin marketplace add <dir>). "
+    + "A Claude Code release without skills-directory plugins does not load it either.";
+const CODEX_TRUST = "Codex runs these hooks only after you trust them once with /hooks; until then the Slack message covers each ask.";
+/** Runs the Claude CLI with the environment doctor was given on top of the process's own (CLAUDE_CONFIG_DIR, for one). */
+const defaultRun = (env) => (file, args) => new Promise((resolve, reject) => {
+    execFile(file, args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024, env: { ...process.env, ...env } }, (error, stdout) => (error ? reject(error) : resolve({ stdout })));
+});
+/** The three counts of a hub status answer, or null when it is anything else. */
+function parseStatus(value) {
+    if (value === null || typeof value !== "object")
+        return null;
+    const { deliveries, live_sessions: liveSessions, watchers } = value;
+    const counts = [deliveries, liveSessions, watchers];
+    if (!counts.every(count => typeof count === "number" && Number.isSafeInteger(count) && count >= 0))
+        return null;
+    return { deliveries: deliveries, live_sessions: liveSessions, watchers: watchers };
+}
+/** The running hub's counts (its status op), or null when nothing answers with a status within the time limit. Never rejects. */
+export function hubStatus(stateRoot, timeoutMs = 1000) {
+    return new Promise(resolve => {
+        let socket;
+        let buffer = "";
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            socket?.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        try {
+            socket = connect(hubSocketPath(stateRoot));
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        socket.setEncoding("utf8");
+        socket.on("error", () => finish(null));
+        socket.on("close", () => finish(null));
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline < 0) {
+                if (buffer.length > MAX_LINE_BYTES)
+                    finish(null);
+                return;
+            }
+            try {
+                const response = JSON.parse(buffer.slice(0, newline));
+                finish(response.ok === true ? parseStatus(response.status) : null);
+            }
+            catch {
+                finish(null);
+            }
+        });
+        socket.write(encodeLine({ v: 1, op: "status" }));
+    });
+}
+/** true or false from `claude plugin list --json`; null when the Claude CLI cannot tell. Never rejects. */
+export async function claudePluginLoaded(env, run = defaultRun(env)) {
+    try {
+        const { stdout } = await run(env.AI_GATEWAY_LOCAL_RUNNER_CLAUDE_BINARY ?? "claude", ["plugin", "list", "--json"]);
+        const plugins = JSON.parse(stdout);
+        if (!Array.isArray(plugins))
+            return null;
+        const plugin = plugins.find(entry => entry?.id === PLUGIN_ID);
+        return plugin !== undefined && plugin.enabled !== false;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The asks section of doctor. The integrations go through statusOf, which reads the dir the environment names and the dir
+ * install recorded, and reports an app whose home cannot be found (INTEGRATION_HOME_UNKNOWN) on its own entry.
+ */
+export async function asksDoctorReport(input) {
+    const [status, statuses] = await Promise.all([hubStatus(input.stateRoot), Promise.all(APPS.map(app => statusOf(app, input.env, input.stateRoot)))]);
+    const integrations = [];
+    for (const report of statuses) {
+        if (report.state !== "installed") {
+            integrations.push(report);
+            continue;
+        }
+        if (report.app === "codex") {
+            integrations.push({ ...report, action: CODEX_TRUST });
+            continue;
+        }
+        const loaded = await claudePluginLoaded(input.env, input.run);
+        integrations.push({ ...report, ...(loaded === null ? {} : { loaded }), ...(loaded === false ? { action: CLAUDE_NOT_LOADED } : {}) });
+    }
+    return { mode: input.mode, hub: status === null ? { status: "not_running" } : { status: "running", ...status }, integrations };
+}