windows-development-sandbox 1.12.0 → 1.13.0

package/dist/app/features/health/health.def.js

@@ -131,6 +131,7 @@ export const lastHealth = defineQuery({
 });
 export const checkHealth = defineOperation({
     id: 'health.check',
+    access: 'control',
     title: 'Check this PC',
     summary: 'check this PC, the install, your settings and the sandbox (changes nothing)',
     input: z.object({ harness: z.string().optional().describe('agent to check') }),

package/dist/app/features/sandbox/sandbox.def.js

@@ -91,6 +91,7 @@ export const sandboxStatus = defineQuery({
 });
 export const showWindow = defineOperation({
     id: 'sandbox.showWindow',
+    access: 'control',
     title: 'Show the window',
     summary: 'show the sandbox window',
     input: z.object({}),
@@ -100,6 +101,7 @@ export const showWindow = defineOperation({
 });
 export const hideWindow = defineOperation({
     id: 'sandbox.hideWindow',
+    access: 'control',
     title: 'Hide the window',
     summary: 'hide the sandbox window (it keeps running)',
     input: z.object({}),
@@ -109,6 +111,7 @@ export const hideWindow = defineOperation({
 });
 export const stopSandbox = defineOperation({
     id: 'sandbox.stop',
+    access: 'control',
     title: 'Stop the sandbox…',
     summary: "shut the sandbox down (every project's sessions end)",
     input: z.object({}),

package/dist/app/features/sessions/sessions.def.d.ts

@@ -5,6 +5,10 @@ export declare const SessionRowSchema: z.ZodObject<{
     id: z.ZodString;
     launchId: z.ZodString;
     harness: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        shell: "shell";
+        agent: "agent";
+    }>>;
     cwd: z.ZodString;
     project: z.ZodOptional<z.ZodString>;
     phase: z.ZodEnum<{
@@ -36,6 +40,10 @@ export declare const SessionsListSchema: z.ZodObject<{
         id: z.ZodString;
         launchId: z.ZodString;
         harness: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            shell: "shell";
+            agent: "agent";
+        }>>;
         cwd: z.ZodString;
         project: z.ZodOptional<z.ZodString>;
         phase: z.ZodEnum<{
@@ -74,6 +82,10 @@ export declare const listSessions: import("../../kernel/define.js").QueryDef<z.Z
         id: z.ZodString;
         launchId: z.ZodString;
         harness: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            shell: "shell";
+            agent: "agent";
+        }>>;
         cwd: z.ZodString;
         project: z.ZodOptional<z.ZodString>;
         phase: z.ZodEnum<{
@@ -102,6 +114,26 @@ export declare const restartSessions: import("../../kernel/define.js").Operation
 }, z.core.$strip>, z.ZodObject<{
     message: z.ZodString;
 }, z.core.$strip>, "sessions.restart">;
+/** The shells a shell session can run; auto: PowerShell 7 when the sandbox has it, else Windows PowerShell. */
+export declare const SHELL_CHOICES: readonly ["auto", "pwsh", "powershell", "cmd"];
+export declare const startShell: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    project: z.ZodOptional<z.ZodString>;
+    shell: z.ZodDefault<z.ZodEnum<{
+        pwsh: "pwsh";
+        auto: "auto";
+        powershell: "powershell";
+        cmd: "cmd";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    session: z.ZodString;
+    shell: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, "sessions.shell">;
+export declare const closeSession: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    session: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>, "sessions.close">;
 /** The sessions page: one list (a table on the command line), this folder's project first. */
 export declare function sessionsPage(o: SessionsList): Page;
 export declare const sessionsView: import("../../kernel/define.js").ViewDef<{
@@ -116,6 +148,10 @@ export declare const sessionsView: import("../../kernel/define.js").ViewDef<{
             id: z.ZodString;
             launchId: z.ZodString;
             harness: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                shell: "shell";
+                agent: "agent";
+            }>>;
             cwd: z.ZodString;
             project: z.ZodOptional<z.ZodString>;
             phase: z.ZodEnum<{

package/dist/app/features/sessions/sessions.def.js

@@ -1,6 +1,6 @@
-// The agent sessions of the running sandbox: the list (live) and restarting the agents. Pure: schemas, labels and the
-// view; sessions.run.ts does the work. A running session links to its terminal (attach in the menu, the terminal page
-// in the web UI).
+// The sessions of the running sandbox, agents and plain shells: the list (live), restarting the agents, opening a shell
+// and closing a session. Pure: schemas, labels and the view; sessions.run.ts does the work. A running session links to
+// its terminal (attach in the menu and on the command line, the terminal page in the web UI).
 import { z } from 'zod';
 import { action, ago, defineOperation, defineQuery, defineView, link, } from '../../kernel/index.js';
 const ViewersSchema = z.object({ viewers: z.number(), remote: z.number() });
@@ -8,7 +8,9 @@ const ViewersSchema = z.object({ viewers: z.number(), remote: z.number() });
 export const SessionRowSchema = z.object({
     id: z.string().describe('The session'),
     launchId: z.string(),
-    harness: z.string().describe('The agent'),
+    harness: z.string().describe('The agent, or the shell (pwsh, powershell, cmd)'),
+    /** A plain shell rather than an agent (absent: an agent). */
+    kind: z.enum(['agent', 'shell']).optional(),
     cwd: z.string().describe('Its folder in the sandbox'),
     project: z.string().optional(),
     phase: z.enum(['starting', 'running', 'exited', 'failed']).describe('What it is doing'),
@@ -50,7 +52,7 @@ export function orderedSessions(list) {
 export const listSessions = defineQuery({
     id: 'sessions.list',
     title: 'Sessions',
-    summary: 'list agent sessions and who is attached',
+    summary: 'list sessions (agents and shells) and who is attached',
     input: z.object({ wide: z.boolean().default(false).describe("also show each session's folder") }),
     output: SessionsListSchema,
     live: { everyMs: 2500 },
@@ -65,6 +67,7 @@ export const listSessions = defineQuery({
 });
 export const restartSessions = defineOperation({
     id: 'sessions.restart',
+    access: 'control',
     title: 'Restart agents',
     summary: "restart this project's running agents in place; they resume their conversation",
     input: z.object({
@@ -82,19 +85,71 @@ export const restartSessions = defineOperation({
         },
     },
 });
+/** Agent and project names as the web UI has always accepted them. */
+const NameText = z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/);
+const SessionId = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+/** The shells a shell session can run; auto: PowerShell 7 when the sandbox has it, else Windows PowerShell. */
+export const SHELL_CHOICES = ['auto', 'pwsh', 'powershell', 'cmd'];
+/** The session the operation opened, as a link to its terminal. */
+function openedSession(o) {
+    return { kind: 'terminal', session: o.session };
+}
+export const startShell = defineOperation({
+    id: 'sessions.shell',
+    title: 'New shell',
+    summary: 'open PowerShell or cmd in a project of the running sandbox, as a session you can attach to',
+    input: z.object({
+        project: NameText.optional().describe("The project of the running sandbox (default: this folder's, else asked)"),
+        shell: z
+            .enum(SHELL_CHOICES)
+            .default('auto')
+            .describe('The shell: pwsh, powershell or cmd (default: pwsh if present)'),
+    }),
+    output: z.object({
+        session: z.string().describe('The new session'),
+        shell: z.string().describe('The shell it runs'),
+        message: z.string().describe('What happened'),
+    }),
+    // A shell runs anything as you: someone you let in remotely may type into one you opened, never open one.
+    access: 'owner',
+    text: (o) => o.message,
+    opens: openedSession,
+    cli: {
+        name: 'shell',
+        group: 'Sessions',
+        positional: ['project'],
+        flags: { shell: { flag: '--shell', value: 'name', choices: ['pwsh', 'powershell', 'cmd'] } },
+        json: true,
+        examples: [
+            "sandbox shell                      PowerShell in this folder's project, in this terminal (Ctrl+] detaches)",
+            'sandbox shell api --shell cmd      cmd in the project api',
+        ],
+    },
+});
+export const closeSession = defineOperation({
+    id: 'sessions.close',
+    title: 'Close',
+    summary: 'end a running session (an agent or a shell) and every program it started',
+    input: z.object({ session: SessionId.describe('The session to close') }),
+    output: z.object({ message: z.string().describe("The sandbox's answer") }),
+    access: 'control',
+    danger: true,
+    text: (o) => o.message,
+    cli: { name: 'close', group: 'Sessions', positional: ['session'], examples: ['sandbox close 4f2c9a'] },
+});
 function sessionItem(s, wide) {
     const state = s.phase + (s.exitCode !== undefined ? ' (' + s.exitCode + ')' : '');
     const running = s.phase === 'running';
     return {
         id: s.id,
-        label: s.harness + '  ' + (s.projectName ?? '-'),
+        label: (s.kind === 'shell' ? s.harness + ' (shell)' : s.harness) + '  ' + (s.projectName ?? '-'),
         hint: state + '  ' + ago(s.startedAt),
         badges: [{ text: s.phase, tone: running ? 'ok' : s.phase === 'failed' ? 'danger' : 'muted' }],
         group: s.here ? "This folder's project" : 'Other sessions',
         marked: s.here,
         icon: s.harness,
         description: running
-            ? "Opens this session's terminal (in a terminal, Ctrl+] detaches; the session keeps running)."
+            ? "Opens this session's terminal (in a terminal, Ctrl+] detaches; the session keeps running). x closes it."
             : undefined,
         details: ['Session   ' + s.id, 'Folder    ' + s.cwd, 'Attached  ' + viewerText(s.viewers)],
         cells: {
@@ -108,6 +163,9 @@ function sessionItem(s, wide) {
             started: ago(s.startedAt),
         },
         ...(running && s.canOpen ? { primary: link({ kind: 'terminal', session: s.id }, 'Open', { verb: 'attach' }) } : {}),
+        ...(running
+            ? { actions: [action(closeSession, { session: s.id }, { key: 'x', verb: 'close', importance: 1 })] }
+            : {}),
         ...(running ? {} : { disabled: 'This session has ended.' }),
         ...(running && !s.canOpen ? { disabled: 'Not reachable from this PC.' } : {}),
     };
@@ -150,6 +208,16 @@ export function sessionsPage(o) {
         ],
         actions: [
             ...(o.sandboxRunning ? [{ ...start, label: 'New session', key: 'n', verb: 'new session', importance: 1 }] : []),
+            ...(o.sandboxRunning
+                ? [
+                    action(startShell, { shell: 'auto' }, {
+                        key: 's',
+                        verb: 'new shell',
+                        importance: 1,
+                        description: 'Opens PowerShell in a project of the sandbox, as a session like the agents.',
+                    }),
+                ]
+                : []),
             ...(sessions.length
                 ? [action(restartSessions, { all: false }, { key: 'r', verb: 'restart agents', importance: 1 })]
                 : []),
@@ -172,8 +240,8 @@ export function sessionsPage(o) {
 export const sessionsView = defineView({
     id: 'sessions',
     title: 'Sessions',
-    summary: 'The agent sessions of the running sandbox: open one, restart the agents.',
+    summary: 'The sessions of the running sandbox: open one, restart the agents, open a shell, close one.',
     queries: { sessions: listSessions },
-    operations: [restartSessions],
+    operations: [restartSessions, startShell, closeSession],
     build: ({ sessions }) => sessionsPage(sessions),
 });

package/dist/app/features/sessions/sessions.run.d.ts

@@ -1,3 +1,4 @@
+import { type Context } from '../../../cli/commands/context.js';
 export declare const listSessionsRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{
     wide: import("zod").ZodDefault<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
@@ -9,6 +10,10 @@ export declare const listSessionsRun: import("../../kernel/define.js").Implement
         id: import("zod").ZodString;
         launchId: import("zod").ZodString;
         harness: import("zod").ZodString;
+        kind: import("zod").ZodOptional<import("zod").ZodEnum<{
+            shell: "shell";
+            agent: "agent";
+        }>>;
         cwd: import("zod").ZodString;
         project: import("zod").ZodOptional<import("zod").ZodString>;
         phase: import("zod").ZodEnum<{
@@ -30,10 +35,28 @@ export declare const listSessionsRun: import("../../kernel/define.js").Implement
         }, import("zod/v4/core").$strip>>>;
         canOpen: import("zod").ZodBoolean;
     }, import("zod/v4/core").$strip>>;
-}, import("zod/v4/core").$strip>, "sessions.list">, import("../../../cli/commands/context.js").Context>;
+}, import("zod/v4/core").$strip>, "sessions.list">, Context>;
 export declare const restartSessionsRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
     harness: import("zod").ZodOptional<import("zod").ZodString>;
     all: import("zod").ZodDefault<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     message: import("zod").ZodString;
-}, import("zod/v4/core").$strip>, "sessions.restart">, import("../../../cli/commands/context.js").Context>;
+}, import("zod/v4/core").$strip>, "sessions.restart">, Context>;
+export declare const startShellRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    project: import("zod").ZodOptional<import("zod").ZodString>;
+    shell: import("zod").ZodDefault<import("zod").ZodEnum<{
+        pwsh: "pwsh";
+        auto: "auto";
+        powershell: "powershell";
+        cmd: "cmd";
+    }>>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    session: import("zod").ZodString;
+    shell: import("zod").ZodString;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "sessions.shell">, Context>;
+export declare const closeSessionRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    session: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "sessions.close">, Context>;

package/dist/app/features/sessions/sessions.run.js

@@ -1,13 +1,17 @@
-// The sessions feature's work: the list (as this user may see it under the sharing rules) and restarting the agents.
-import { safeText } from '../../../core/util/index.js';
+// The sessions feature's work: the list (as this user may see it under the sharing rules), restarting the agents,
+// opening a shell in a project of the running sandbox and closing a session.
+import { fail, safeText } from '../../../core/util/index.js';
+import { RunDir } from '../../../shared/channel/index.js';
 import { hostEndpoint } from '../../../host/channel/index.js';
 import { isSandboxRunning } from '../../../host/sandbox/index.js';
 import { requireOnPc, requireRunning } from '../../../cli/commands/context.js';
+import { locateHere } from '../../../cli/commands/projects/here.js';
 import { lookAtSandbox, useSharedSandbox } from '../../../cli/commands/shared-use.js';
 import { SessionsService } from '../../../cli/services/index.js';
+import { runningProjects } from '../../../cli/services/web-service.js';
 import { implement, typedConfirm } from '../../context.js';
 import { cancelled } from '../../kernel/index.js';
-import { listSessions, restartSessions } from './sessions.def.js';
+import { closeSession, listSessions, restartSessions, startShell } from './sessions.def.js';
 /** A listed session as the surfaces see it: no attach address or token, text from the sandbox made safe. */
 function sessionRow(s) {
     const { attach: _attach, ...rest } = s;
@@ -56,3 +60,67 @@ export const restartSessionsRun = implement(restartSessions, async (ctx, input,
     io.progress('Restarting the agents' + (scope.guest ? ' of ' + scope.projectName : ''));
     return { message: safeText(await service.restart(input.harness ?? null, scope.guest)) };
 });
+/** Where a new shell opens: the project named, else the one of the current folder, else the only one, else asked. */
+async function shellPlace(ctx, project, io) {
+    const projects = runningProjects({ ctx, line: null, limited: false, owner: null });
+    if (project !== undefined) {
+        const named = projects.find((p) => p.name.toLowerCase() === project.toLowerCase());
+        if (!named)
+            fail('The running sandbox has no project "' + project + '".', 'sandbox status lists its projects.');
+        return { name: named.name, guest: named.guest };
+    }
+    const here = locateHere(ctx, new RunDir(ctx.dataPath).readSandboxStatus());
+    if (here.guestDir)
+        return { name: here.project?.name, guest: here.guestDir };
+    if (!projects.length)
+        fail('The running sandbox has no projects.');
+    if (projects.length === 1)
+        return projects[0];
+    const chosen = await io.choose({
+        title: 'Which project?',
+        choices: projects.map((p) => ({ value: p.name, label: p.name, description: p.guest })),
+    });
+    const picked = projects.find((p) => p.name === chosen);
+    if (!picked)
+        cancelled();
+    return picked;
+}
+export const startShellRun = implement(startShell, async (asked, input, io) => {
+    requireOnPc('shell');
+    requireRunning();
+    const ctx = await useSharedSandbox(asked, { kind: 'use' }, typedConfirm(io));
+    const place = await shellPlace(ctx, input.project, io);
+    io.progress('Opening ' + (input.shell === 'auto' ? 'a shell' : input.shell) + ' in ' + (place.name ?? place.guest));
+    const session = await new SessionsService(ctx).openShell(input.shell, place.guest);
+    const shell = safeText(session.harness);
+    return {
+        session: safeText(session.id),
+        shell,
+        message: 'Opened ' + shell + ' in ' + safeText(place.name ?? place.guest) + ' (session ' + safeText(session.id) + ').',
+    };
+});
+export const closeSessionRun = implement(closeSession, async (asked, input, io) => {
+    requireOnPc('close');
+    requireRunning();
+    const find = (ctx) => new SessionsService(ctx).running(null).find((s) => s.id === input.session);
+    // Anyone the sandbox is shared with may close a shell; an agent session is its owner's to end.
+    const ctx = await useSharedSandbox(asked, (shared) => find(shared)?.kind === 'shell' ? { kind: 'use' } : { kind: 'owner-only', what: 'close an agent session' }, typedConfirm(io));
+    const session = find(ctx);
+    if (!session)
+        fail('No running session ' + input.session + '.', 'sandbox sessions lists the running ones.');
+    const what = safeText(session.harness) + (session.kind === 'shell' ? ' (shell)' : '');
+    const yes = await io.confirm({
+        title: 'Close ' + what + ' session ' + input.session + '?',
+        lines: [
+            'It ends, with every program it started.' +
+                (session.kind === 'shell' ? '' : ' The agent can pick its conversation up again in a new session.'),
+        ],
+        yes: 'Close',
+        danger: true,
+        implied: true,
+    });
+    if (!yes)
+        cancelled();
+    io.progress('Closing session ' + input.session);
+    return { message: safeText(await new SessionsService(ctx).close(input.session)) };
+});

package/dist/app/features/settings/settings.def.d.ts

@@ -94,6 +94,14 @@ export declare const getSetting: import("../../kernel/define.js").QueryDef<z.Zod
     key: z.ZodString;
     value: z.ZodUnknown;
 }, z.core.$strip>, "settings.get">;
+/**
+ * The settings someone with control (not the owner) may change: how attaching and reopening sessions behave, in your
+ * own settings file. Everything else (folders, agents, secrets, network, storage, sharing, the audit log, remote
+ * access) changes what the sandbox can reach or who can come in, so it is the owner's (docs/design/remote-access.md).
+ */
+export declare const CONTROL_SETTINGS: readonly string[];
+/** settings.set / settings.reset: control for CONTROL_SETTINGS in the user file, owner for everything else. */
+export declare function controlSettingAccess(input: unknown): 'control' | 'owner';
 export declare const setSetting: import("../../kernel/define.js").OperationDef<z.ZodObject<{
     scope: z.ZodDefault<z.ZodEnum<{
         project: "project";

package/dist/app/features/settings/settings.def.js

@@ -65,8 +65,24 @@ export const getSetting = defineQuery({
     surfaces: { except: { menu: 'Settings shows every value', web: 'the Settings page shows every value' } },
     cli: { name: 'config', action: 'get', positional: ['key'] },
 });
+/**
+ * The settings someone with control (not the owner) may change: how attaching and reopening sessions behave, in your
+ * own settings file. Everything else (folders, agents, secrets, network, storage, sharing, the audit log, remote
+ * access) changes what the sandbox can reach or who can come in, so it is the owner's (docs/design/remote-access.md).
+ */
+export const CONTROL_SETTINGS = ['attach.', 'resume.'];
+/** settings.set / settings.reset: control for CONTROL_SETTINGS in the user file, owner for everything else. */
+export function controlSettingAccess(input) {
+    const o = (input ?? {});
+    const key = typeof o.key === 'string' ? o.key : '';
+    const userFile = o.scope === undefined || o.scope === 'user';
+    return userFile && CONTROL_SETTINGS.some((prefix) => key.startsWith(prefix) && key.length > prefix.length)
+        ? 'control'
+        : 'owner';
+}
 export const setSetting = defineOperation({
     id: 'settings.set',
+    access: controlSettingAccess,
     title: 'Change a setting',
     summary: 'change one setting (text is read like the command line: true/on, numbers, JSON)',
     input: z.object({
@@ -80,6 +96,7 @@ export const setSetting = defineOperation({
 });
 export const resetSetting = defineOperation({
     id: 'settings.reset',
+    access: controlSettingAccess,
     title: 'Reset a setting',
     summary: 'put one setting back to its default (in a project file: remove it)',
     input: z.object({ scope: ScopeSchema.default('user'), key: KeySchema }),

package/dist/app/features/web/web.def.d.ts

@@ -4,12 +4,18 @@ export declare const WebStatusSchema: z.ZodObject<{
     running: z.ZodBoolean;
     port: z.ZodNullable<z.ZodNumber>;
     address: z.ZodNullable<z.ZodString>;
+    lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type WebStatus = z.output<typeof WebStatusSchema>;
 export declare const webStatus: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
     running: z.ZodBoolean;
     port: z.ZodNullable<z.ZodNumber>;
     address: z.ZodNullable<z.ZodString>;
+    lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>, "web.status">;
 export declare const startWeb: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
     port: z.ZodNumber;
@@ -29,5 +35,8 @@ export declare const webView: import("../../kernel/define.js").ViewDef<{
         running: z.ZodBoolean;
         port: z.ZodNullable<z.ZodNumber>;
         address: z.ZodNullable<z.ZodString>;
+        lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, "web.status">;
 }, Record<string, never>, "web">;

package/dist/app/features/web/web.def.js

@@ -8,6 +8,13 @@ export const WebStatusSchema = z.object({
     running: z.boolean().describe('The web UI server answers'),
     port: z.number().nullable().describe('Its port on 127.0.0.1, when it runs'),
     address: z.string().nullable().describe('Its address (without the login token), when it runs'),
+    lanAddress: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Its address on your network for paired devices (LAN mode), when it listens there'),
+    lanFingerprint: z.string().nullable().optional().describe("The LAN certificate's SHA-256 fingerprint"),
+    lanProblem: z.string().nullable().optional().describe('Why LAN mode is on but not listening'),
 });
 const MessageSchema = z.object({ message: z.string().describe('What happened') });
 export const webStatus = defineQuery({
@@ -18,7 +25,11 @@ export const webStatus = defineQuery({
     output: WebStatusSchema,
     surfaces: NOT_ON_WEB,
     text: (o) => o.running && o.port
-        ? 'The web UI is running at http://127.0.0.1:' + o.port + '/ (sandbox web open signs you in).'
+        ? 'The web UI is running at http://127.0.0.1:' +
+            o.port +
+            '/ (sandbox web open signs you in).' +
+            (o.lanAddress ? '\nOn your network: ' + o.lanAddress + ' (certificate ' + o.lanFingerprint + ')' : '') +
+            (o.lanProblem ? '\nLAN mode is on but not listening: ' + o.lanProblem : '')
         : 'The web UI is not running (sandbox web start).',
     cli: { name: 'web', action: 'status', json: true },
 });
@@ -73,6 +84,20 @@ export function webPage(o) {
                         tone: o.running ? 'ok' : 'muted',
                     },
                     ...(o.address ? [{ id: 'address', label: 'Address', value: o.address + '  (this PC only)' }] : []),
+                    ...(o.lanAddress
+                        ? [
+                            {
+                                id: 'lan',
+                                label: 'On your network',
+                                value: o.lanAddress,
+                                description: 'Type this into the phone, then enter the code from Remote access > Allow a new device.',
+                                details: o.lanFingerprint ? ['Certificate ' + o.lanFingerprint] : undefined,
+                            },
+                        ]
+                        : []),
+                    ...(o.lanProblem
+                        ? [{ id: 'lan-problem', label: 'LAN mode', value: o.lanProblem, tone: 'warn' }]
+                        : []),
                 ],
                 actions: o.running ? [open, stop] : [start, open],
                 notes: [{ text: 'Loopback only, behind a token. Open signs you in.', tone: 'muted' }],

package/dist/app/features/web/web.run.d.ts

@@ -10,6 +10,9 @@ export declare const webStatusRun: import("../../kernel/define.js").Implementati
     running: import("zod").ZodBoolean;
     port: import("zod").ZodNullable<import("zod").ZodNumber>;
     address: import("zod").ZodNullable<import("zod").ZodString>;
+    lanAddress: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    lanFingerprint: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    lanProblem: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>, "web.status">, import("../../../cli/commands/context.js").Context>;
 export declare const startWebRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     port: import("zod").ZodNumber;

package/dist/app/features/web/web.run.js

@@ -60,7 +60,15 @@ export const webStatusRun = implement(webStatus, async (ctx) => {
     requireOnPc('web');
     const { running, state } = await controlOf(ctx).status();
     const port = running && state ? state.port : null;
-    return { running, port, address: port ? 'http://127.0.0.1:' + port + '/' : null };
+    const lan = running ? (state?.lan ?? null) : null;
+    return {
+        running,
+        port,
+        address: port ? 'http://127.0.0.1:' + port + '/' : null,
+        lanAddress: lan?.url ?? null,
+        lanFingerprint: lan?.fingerprint ?? null,
+        lanProblem: lan?.problem ?? null,
+    };
 });
 export const startWebRun = implement(startWeb, async (ctx, _input, io) => {
     requireOnPc('web');
@@ -73,8 +81,8 @@ export const openWebRun = implement(openWeb, async (ctx, _input, io) => {
     const started = await startServer(ctx, io, control);
     if (started.wasRunning)
         io.log(started.message);
-    const { state } = await control.status();
-    if (!state)
+    const { running, state } = await control.status();
+    if (!running || !state)
         return fail('The web UI stopped right away.', 'Run sandbox web start again.');
     openBrowser(control.url(state));
     return { message: 'Opened in your browser.' };

package/dist/app/kernel/access.d.ts

@@ -0,0 +1,33 @@
+/** What a definition needs. Default (fails closed): a query needs view, an operation owner. */
+export type Access = 'view' | 'control' | 'owner';
+/** A role the owner can give: view only, or full control (everything but the owner's own things). */
+export type RemoteRole = 'view' | 'control';
+/** Who runs a definition: the owner, or someone the owner let in. */
+export type Caller = {
+    readonly kind: 'owner';
+} | {
+    readonly kind: 'windows';
+    readonly user: string;
+    readonly role: RemoteRole;
+} | {
+    readonly kind: 'device';
+    readonly id: string;
+    readonly name: string;
+    readonly role: RemoteRole;
+};
+export declare const OWNER: Caller;
+/** A definition's need, as written: fixed, or from its input (settings.set on a web.* key needs owner). */
+export type AccessRule = Access | ((input: unknown) => Access);
+/** The most a caller may do. */
+export declare function callerAccess(caller: Caller): Access;
+/** The caller may run something that needs `need`. */
+export declare function allows(caller: Caller, need: Access): boolean;
+/** What a definition needs for this input. A rule that throws on a strange input needs owner. */
+export declare function accessNeeded(def: {
+    readonly kind: 'operation' | 'query';
+    readonly access?: AccessRule;
+}, input: unknown): Access;
+/** Who the caller is, in a few words (the audit log, the page's header). */
+export declare function callerLabel(caller: Caller): string;
+/** The refusal text for a caller that may not. */
+export declare function refusalText(caller: Caller, need: Access): string;

package/dist/app/kernel/access.js

@@ -0,0 +1,44 @@
+// Who may run what (docs/design/remote-access.md): every definition needs view, control or owner; the caller of a run
+// has a role. The owner (at the PC, or through the token link) may do everything; another Windows user of this PC or a
+// paired device has the role the owner gave them, never owner. Pure (the web bundle shows what the role allows).
+export const OWNER = { kind: 'owner' };
+const RANK = { view: 0, control: 1, owner: 2 };
+/** The most a caller may do. */
+export function callerAccess(caller) {
+    return caller.kind === 'owner' ? 'owner' : caller.role;
+}
+/** The caller may run something that needs `need`. */
+export function allows(caller, need) {
+    return RANK[callerAccess(caller)] >= RANK[need];
+}
+/** What a definition needs for this input. A rule that throws on a strange input needs owner. */
+export function accessNeeded(def, input) {
+    const rule = def.access;
+    if (rule === undefined)
+        return def.kind === 'query' ? 'view' : 'owner';
+    if (typeof rule === 'string')
+        return rule;
+    try {
+        return rule(input);
+    }
+    catch {
+        return 'owner';
+    }
+}
+/** Who the caller is, in a few words (the audit log, the page's header). */
+export function callerLabel(caller) {
+    switch (caller.kind) {
+        case 'owner':
+            return 'you';
+        case 'windows':
+            return 'Windows user ' + caller.user;
+        case 'device':
+            return 'device ' + caller.name;
+    }
+}
+/** The refusal text for a caller that may not. */
+export function refusalText(caller, need) {
+    if (need === 'owner')
+        return 'Only the owner of this PC can do that, at the PC.';
+    return callerAccess(caller) === 'view' ? 'Your access is view only.' : 'You may not do that.';
+}