Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(messaging): machine-local agentMessaging default (ships off)
enes4c12a285b084
diff --git a/CLAUDE.md b/CLAUDE.mdindex 72192a8f2..3a36f13d0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2525,6 +2525,32 @@ else, and its context links must keep classifying across restarts).Edition refuses every `--set` by name** — its headless opt-in (#537) is not consent to grantcapabilities, and there is no dialog; `--get` answers from `capabilityProjectFor`, own project only.Mobile: N/A (the phone issues no control verbs).+ **Agent messaging's MACHINE DEFAULT (`settings.agentMessagingDefault`, 2026-09, ships OFF).** A+ project whose `.nodeterm/project.json` carries NO `agentMessaging` value is answered by this+ machine's settings.json; the rule is ONE function, `projectCapabilityEffective`+ (`@shared/project-capability-consent`), and `projectCapabilityGrantedFor` now REQUIRES the+ defaults argument so a consumer that forgot it fails to compile instead of reading every+ unconfigured project as off while Settings reads it as on. Four rules: (1) an explicit `true` still+ needs this machine's `'kept'` — `needsCapabilityNotice` is untouched and stays keyed on an explicit+ `true`, so a cloned file still notices and a project on only by default never does; (2) OFF is now+ WRITTEN — `setProjectCapability(…, false)` stores a literal `false` for a capability in+ `CAPABILITY_MACHINE_DEFAULTS` (browser control has none and still deletes the field), because+ absence now means "use the default"; `readProjectCapabilities` carries that `false` through the+ file; (3) an ABSENT field with a recorded `'declined'` stays off — that is how every pre-default+ build wrote "off", and a user's explicit no must not be undone by a default switched on later;+ "Use this machine's default" (`resetProjectCapabilityToDefault`) therefore clears the field AND the+ answer; (4) the default is forbidden to the `settings` verb (a grant over every project, clones+ included). **This does not trip the `project-capabilities.ts` header's trigger**: the notice is not+ dropped, and what the default answers is absence, whose value lives in machine-local settings.json.+ **Why it ships OFF:** `core/agents/pane-ownership.ts` records a pane's owner only on a FRESH spawn,+ so after an app restart or update every surviving pane is `unproven-target-owner` and refused —+ "on by default" would be false after every restart. The flip is a separate one-line change that+ waits for a cross-restart ownership proof (#659's signed record is the candidate). Settings →+ Agents shows the machine switch, and the per-project row is a three-way choice (default / on /+ off) plus "On in <project> (this machine's default)" — a two-position switch cannot draw absence.+ Downgrade: a pre-default build writes `false` back as a deleted field, which this build then reads+ as "use the default". Server Edition reads the same grant from its own settings.json; Mobile: N/A+ (the phone has no capability switch).**Review panel (`verify`, 2026-07):** `verify --node <id> [--lenses …] [--focus …] [--agent …][--synthesis off]` opens one reviewer per LENS, each armed behind the target (`--after`) andbridged to it, wrapped in a `Verify: <title>` group, plus a judge armed behind the whole panel.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex d4ad3bcab..b83a5f8f5 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -162,6 +162,10 @@ lane unaffected.act only on the user's own machine-local choice — and keep `default` distinct from `global`,because reading an unset setting as a deliberate choice is reading consent into silence. Anythingmachine-local goes in `settings.json`; nothing that grants a capability goes in `project.json`.+ A machine-local DEFAULT for a project capability (`agentMessagingDefault`) is allowed only because+ it answers ABSENCE: an explicit `true` in `project.json` still needs this machine's recorded+ answer, an explicit `false` still wins, and "off" must therefore be written as a literal `false`.+ Read grants through `projectCapabilityGrantedFor(project, cap, settings)` — never the file bit.- **Nothing an agent asks for may take the user's screen.** Canvas control routes by SOURCE: therequest names the agent's own node, and the dispatch has to find the canvas that owns it. Fordiff --git a/src/core/agents/agent-messaging.ts b/src/core/agents/agent-messaging.tsindex dcaebdc4a..9ccac5a65 100644--- a/src/core/agents/agent-messaging.ts+++ b/src/core/agents/agent-messaging.ts@@ -50,7 +50,10 @@ import {projectCapabilityGrantedFor,type CapabilityAckMap} from '../project-capability-consent'-import type { ProjectCapability } from '../../shared/project-capabilities'+import type {+ CapabilityMachineDefaults,+ ProjectCapability+} from '../../shared/project-capabilities'/** The little the service needs to know about a stored node. */export interface MessagingStoredNode {@@ -137,9 +140,15 @@ export function messagingEnabledVia(projectId: string) =>| (Partial<Record<ProjectCapability, unknown>> & { capabilityAck?: CapabilityAckMap })- | undefined+ | undefined,+ /** This machine's settings, read per call like the project — so a change to the machine default+ * (settings.json, `agentMessagingDefault`) takes effect on the next delivery, exactly as an+ * off-toggle does. Required: a shell that forgot it would read every unconfigured project as off+ * while the Settings page reads it as on. */+ getDefaults: () => CapabilityMachineDefaults): (projectId: string) => boolean {- return (projectId) => projectCapabilityGrantedFor(getProject(projectId), 'agentMessaging')+ return (projectId) =>+ projectCapabilityGrantedFor(getProject(projectId), 'agentMessaging', getDefaults())}// ── The receipt bus ───────────────────────────────────────────────────────────────────────────diff --git a/src/core/project-capability-consent.test.ts b/src/core/project-capability-consent.test.tsindex 2808118ce..5ff689c2e 100644--- a/src/core/project-capability-consent.test.ts+++ b/src/core/project-capability-consent.test.ts@@ -62,39 +62,36 @@ describe('projectCapabilityGranted — only an explicit KEPT grants', () => {describe('projectCapabilityGrantedFor — the ONE consumer-facing wiring (PR 4 ledger, PR 6 messagingEnabled)', () => {const cap = 'agentBrowserControl' as constit('derives both halves from the project and refuses every non-granting shape', () => {- expect(projectCapabilityGrantedFor(undefined, cap)).toBe(false)- expect(projectCapabilityGrantedFor({ ...baseProject }, cap)).toBe(false)+ expect(projectCapabilityGrantedFor(undefined, cap, {})).toBe(false)+ expect(projectCapabilityGrantedFor({ ...baseProject }, cap, {})).toBe(false)// pending notice (hostile clone window)- expect(projectCapabilityGrantedFor({ ...baseProject, agentBrowserControl: true }, cap)).toBe(false)+ expect(projectCapabilityGrantedFor({ ...baseProject, agentBrowserControl: true }, cap, {})).toBe(false)// recorded decline + re-arrived trueexpect(projectCapabilityGrantedFor({ ...baseProject, agentBrowserControl: true, capabilityAck: { [cap]: 'declined' } },- cap- )+ cap, {})).toBe(false)// non-literal-true file value never grants, answer or no answerexpect(projectCapabilityGrantedFor({ ...baseProject, agentBrowserControl: 'true', capabilityAck: { [cap]: 'kept' } } as never,- cap- )+ cap, {})).toBe(false)})it('grants exactly for literal true + kept', () => {expect(projectCapabilityGrantedFor({ ...baseProject, agentBrowserControl: true, capabilityAck: { [cap]: 'kept' } },- cap- )+ cap, {})).toBe(true)})it('ignores a prototype-inherited flag or answer — own properties only', () => {// M-1 (PR #213 review): unreachable from JSON.parse, but in-process objects can inherit.const inheritedFlag = Object.create({ agentBrowserControl: true }) as Project- expect(projectCapabilityGrantedFor({ ...baseProject, ...inheritedFlag, capabilityAck: { [cap]: 'kept' } }, cap)).toBe(false)+ expect(projectCapabilityGrantedFor({ ...baseProject, ...inheritedFlag, capabilityAck: { [cap]: 'kept' } }, cap, {})).toBe(false)const proto = Object.create({ agentBrowserControl: true, capabilityAck: { [cap]: 'kept' } }) as Project- expect(projectCapabilityGrantedFor(proto, cap)).toBe(false)+ expect(projectCapabilityGrantedFor(proto, cap, {})).toBe(false)})})@@ -164,3 +161,80 @@ describe('one decider, two consumers', () => {expect(projectCapabilityGrantedFor).toBe(shared.projectCapabilityGrantedFor)})})++describe('the MACHINE DEFAULT answers absence — and only absence (agentMessaging)', () => {+ const cap = 'agentMessaging' as const+ const on = { agentMessagingDefault: true }+ const off = { agentMessagingDefault: false }++ it('a project whose file says NOTHING reads on under the default, off without it', () => {+ expect(projectCapabilityGrantedFor({}, cap, on)).toBe(true)+ expect(projectCapabilityGrantedFor({}, cap, off)).toBe(false)+ expect(projectCapabilityGrantedFor({}, cap, {})).toBe(false)+ expect(shared.projectCapabilityEffective({}, cap, on)).toEqual({+ on: true,+ source: 'default',+ pendingNotice: false+ })+ })++ it('an explicit false in the file stays OFF, whatever the default', () => {+ expect(projectCapabilityGrantedFor({ agentMessaging: false }, cap, on)).toBe(false)+ expect(+ projectCapabilityGrantedFor(+ { agentMessaging: false, capabilityAck: { agentMessaging: 'kept' } },+ cap,+ on+ )+ ).toBe(false)+ })++ it('a CLONED true still needs this machine’s answer — the default is not consent for it', () => {+ const cloned = { agentMessaging: true }+ expect(projectCapabilityGrantedFor(cloned, cap, on)).toBe(false)+ expect(needsCapabilityNotice({ capability: cap, enabledInFile: true, answer: undefined })).toBe(+ true+ )+ expect(shared.projectCapabilityEffective(cloned, cap, on).pendingNotice).toBe(true)+ })++ it('a recorded DECLINE keeps an absent field off — the pre-default builds wrote "off" that way', () => {+ expect(+ projectCapabilityGrantedFor({ capabilityAck: { agentMessaging: 'declined' } }, cap, on)+ ).toBe(false)+ })++ it('a project on only by default raises no notice: the decider is keyed on an EXPLICIT true', () => {+ // CapabilityNotice feeds `enabledInFile` from the strict file flag, which is false for absence.+ expect(needsCapabilityNotice({ capability: cap, enabledInFile: false, answer: undefined })).toBe(+ false+ )+ })++ it('the default is read strictly: a hand-edited "true" string in settings.json is off', () => {+ expect(+ projectCapabilityGrantedFor({}, cap, { agentMessagingDefault: 'true' as unknown as boolean })+ ).toBe(false)+ })++ it('a malformed file value is absence, not an explicit off — and not an explicit on', () => {+ for (const v of ['true', 'false', 0, 1, null, {}]) {+ expect(projectCapabilityGrantedFor({ agentMessaging: v }, cap, on), String(v)).toBe(true)+ expect(projectCapabilityGrantedFor({ agentMessaging: v }, cap, off), String(v)).toBe(false)+ }+ })++ it('browser control has NO default: absence is off even if a caller passes one', () => {+ expect(+ projectCapabilityGrantedFor({}, 'agentBrowserControl', on as Record<string, boolean>)+ ).toBe(false)+ expect(+ projectCapabilityGrantedFor({ agentBrowserControl: false }, 'agentBrowserControl', on)+ ).toBe(false)+ })++ it('the core re-export is the same function object', () => {+ // src/core callers must reach the one rule, not a copy.+ expect(projectCapabilityGrantedFor).toBe(shared.projectCapabilityGrantedFor)+ })+})diff --git a/src/core/workspace-files.test.ts b/src/core/workspace-files.test.tsindex fd23c40bc..0f6657786 100644--- a/src/core/workspace-files.test.ts+++ b/src/core/workspace-files.test.ts@@ -115,6 +115,19 @@ describe('per-project capability fields in the shared file', () => {fileToProject({ ...baseFile, agentBrowserControl: 'true' } as never, { id: 'x' }).agentBrowserControl).toBeUndefined()})+ it('agentMessaging carries an explicit FALSE through the file (it has a machine default); browser control does not', () => {+ const f = projectToFile(project({ agentMessaging: false, agentBrowserControl: false }), 1, 'ts')+ expect(f.agentMessaging).toBe(false)+ expect('agentBrowserControl' in f).toBe(false)+ const back = fileToProject(f, { id: 'x' })+ expect(back.agentMessaging).toBe(false)+ expect(back.agentBrowserControl).toBeUndefined()+ // A non-boolean is still dropped at the boundary — it reads as absence, never as an explicit off.+ const baseFile = projectToFile(project(), 1, 'ts')+ expect(+ fileToProject({ ...baseFile, agentMessaging: 'false' } as never, { id: 'x' }).agentMessaging+ ).toBeUndefined()+ })it('an off capability adds no bytes to the committed file', () => {const f = projectToFile(project(), 1, 'ts')expect('agentBrowserControl' in f).toBe(false)diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.tsindex 84c09a904..b800ecd50 100644--- a/src/core/workspace-store.ts+++ b/src/core/workspace-store.ts@@ -1493,7 +1493,7 @@ export class WorkspaceStore {*/capabilityProjectFor(projectId: string- ): (Partial<Record<ProjectCapability, true>> & { capabilityAck?: CapabilityAckMap }) | undefined {+ ): (Partial<Record<ProjectCapability, boolean>> & { capabilityAck?: CapabilityAckMap }) | undefined {for (const e of this.index?.entries ?? []) {if (e.project) {if (e.project.id !== projectId) continuediff --git a/src/main/agent-messaging-switch.test.ts b/src/main/agent-messaging-switch.test.tsindex 4fea8ffef..9e3b6dd9a 100644--- a/src/main/agent-messaging-switch.test.ts+++ b/src/main/agent-messaging-switch.test.ts@@ -106,11 +106,11 @@ describe('messagingEnabledVia — the grant, never the raw file bit', () => {const run = (project: (Partial<Record<'agentMessaging', unknown>> & { capabilityAck?: CapabilityAckMap }) | undefined) =>deliverFromControl(req,- baseDeps({ messagingEnabled: messagingEnabledVia(() => project) })+ baseDeps({ messagingEnabled: messagingEnabledVia(() => project, () => ({})) }))it('flag true but the clone notice UNANSWERED: refused as switch-off, no pane touched', async () => {- const deps = baseDeps({ messagingEnabled: messagingEnabledVia(() => ({ agentMessaging: true })) })+ const deps = baseDeps({ messagingEnabled: messagingEnabledVia(() => ({ agentMessaging: true }), () => ({})) })const { outcome, reply } = await deliverFromControl(req, deps)expect(outcome).toEqual({ kind: 'notPermitted', reason: 'switch-off' })expect(reply.ok).toBe(false)@@ -127,7 +127,7 @@ describe('messagingEnabledVia — the grant, never the raw file bit', () => {messagingEnabled: messagingEnabledVia(() => ({agentMessaging: true,capabilityAck: { agentMessaging: 'kept' as const }- }))+ }), () => ({}))})const { outcome, reply } = await deliverFromControl(req, deps)expect(outcome.kind).toBe('delivered')@@ -180,7 +180,7 @@ describe('end to end through a REAL WorkspaceStore — the desktop wiring, minusconst storeDeps = (store: WorkspaceStore) =>baseDeps({projects: () => store.persistedCanvases(),- messagingEnabled: messagingEnabledVia((id) => store.capabilityProjectFor(id)),+ messagingEnabled: messagingEnabledVia((id) => store.capabilityProjectFor(id), () => ({})),paneOwnerProject: (id) => paneOwnerProject(id)})@@ -211,6 +211,72 @@ describe('end to end through a REAL WorkspaceStore — the desktop wiring, minusexpect(deps.sent).toEqual([])})+ describe('the MACHINE DEFAULT (settings.json agentMessagingDefault), read per call', () => {+ let defaults: { agentMessagingDefault?: boolean }+ const defaultDeps = (store: WorkspaceStore) =>+ baseDeps({+ projects: () => store.persistedCanvases(),+ messagingEnabled: messagingEnabledVia(+ (id) => store.capabilityProjectFor(id),+ () => defaults+ ),+ paneOwnerProject: (id) => paneOwnerProject(id)+ })+ beforeEach(() => {+ defaults = { agentMessagingDefault: true }+ })++ it('a project.json with NO agentMessaging field delivers under the default — and stops the moment it is turned off', async () => {+ const store = new WorkspaceStore()+ await store.save(ws(project({ cwd: projRoot })))+ const raw = await fs.readFile(path.join(projRoot, '.nodeterm/project.json'), 'utf-8')+ expect(raw).not.toContain('agentMessaging')+ recordFreshSpawnOwner('b1', 'p1')+ const deps = defaultDeps(store)+ expect((await deliverFromControl(req, deps)).outcome.kind).toBe('delivered')+ defaults = { agentMessagingDefault: false }+ resetMessageFlow()+ expect((await deliverFromControl(req, defaultDeps(store))).outcome).toEqual({+ kind: 'notPermitted',+ reason: 'switch-off'+ })+ })++ it('an explicit false committed in project.json refuses, even with the default on', async () => {+ const store = new WorkspaceStore()+ await store.save(ws(project({ cwd: projRoot, agentMessaging: false })))+ const raw = await fs.readFile(path.join(projRoot, '.nodeterm/project.json'), 'utf-8')+ expect(raw).toContain('"agentMessaging": false')+ recordFreshSpawnOwner('b1', 'p1')+ const deps = defaultDeps(store)+ expect((await deliverFromControl(req, deps)).outcome).toEqual({+ kind: 'notPermitted',+ reason: 'switch-off'+ })+ expect(deps.sent).toEqual([])+ })++ it('a CLONED true with no answer on this machine refuses, even with the default on', async () => {+ const store = new WorkspaceStore()+ await store.save(ws(project({ cwd: projRoot, agentMessaging: true })))+ recordFreshSpawnOwner('b1', 'p1')+ expect((await deliverFromControl(req, defaultDeps(store))).outcome).toEqual({+ kind: 'notPermitted',+ reason: 'switch-off'+ })+ })++ it('the default does not rescue an UNPROVEN pane — ownership still gates first', async () => {+ const store = new WorkspaceStore()+ await store.save(ws(project({ cwd: projRoot })))+ // No recordFreshSpawnOwner: e.g. a pane that survived an app restart.+ expect((await deliverFromControl(req, defaultDeps(store))).outcome).toEqual({+ kind: 'notPermitted',+ reason: 'unproven-target-owner'+ })+ })+ })+it('flag committed but DECLINED on this machine: refused as switch-off', async () => {const store = new WorkspaceStore()await store.save(@@ -331,7 +397,7 @@ describe('runtime pane-ownership gate (PR #237 fix round 2) — over a REAL storconst storeDeps = (store: WorkspaceStore) =>baseDeps({projects: () => store.persistedCanvases(),- messagingEnabled: messagingEnabledVia((id) => store.capabilityProjectFor(id)),+ messagingEnabled: messagingEnabledVia((id) => store.capabilityProjectFor(id), () => ({})),paneOwnerProject: (id) => paneOwnerProject(id)})diff --git a/src/main/index.ts b/src/main/index.tsindex 8ef07f641..4a01bc7de 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -1797,12 +1797,17 @@ app.whenReady().then(async () => {hasLiveSession: (id) => ptyManager.hasLiveSession(id),projects: () => workspaceStore.persistedCanvases(),isRemoteNode: (id) => !!ptyManager.sshRemoteForNode(id),- // GLOBAL CONSTRAINT 11: every delivery path is gated behind the per-project switch, OFF by- // default. The switch is the `agentMessaging` capability GRANT: the strict `=== true` flag- // in the hostile git-shared project.json AND this machine's recorded 'kept' answer to the- // clone notice (projectCapabilityGrantedFor — never the raw file bit). Read per call off- // the store's index, so a decline or an off-toggle refuses the very next delivery.- messagingEnabled: messagingEnabledVia((id) => workspaceStore.capabilityProjectFor(id)),+ // GLOBAL CONSTRAINT 11: every delivery path is gated behind the per-project switch. The switch+ // is the `agentMessaging` capability GRANT (projectCapabilityGrantedFor — never the raw file+ // bit): an explicit `true` in the hostile git-shared project.json needs this machine's 'kept'+ // answer to the clone notice, an explicit `false` is off, and an ABSENT value is answered by+ // this machine's settings.json `agentMessagingDefault` (OFF by default). Read per call off the+ // store's index and the settings store, so a decline, an off-toggle or a default change+ // takes effect on the very next delivery.+ messagingEnabled: messagingEnabledVia(+ (id) => workspaceStore.capabilityProjectFor(id),+ () => settingsStore.get()+ ),// Runtime pane ownership: which project actually SPAWNED the target's pane this run// (core/agents/pane-ownership.ts). The gate trusts this over the attacker-writable store to// decide whose grant applies; unproven ⇒ refused (PR #237 fix round 2).diff --git a/src/renderer/components/capability-notice.test.tsx b/src/renderer/components/capability-notice.test.tsxindex 9a593487a..85cb9383f 100644--- a/src/renderer/components/capability-notice.test.tsx+++ b/src/renderer/components/capability-notice.test.tsx@@ -66,7 +66,7 @@ function button(label: string): HTMLButtonElement {/** The grantedness the ledger/messaging wiring computes from the live store, per call. */function grantedNow(): boolean {- return projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), cap)+ return projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), cap, {})}beforeEach(() => {@@ -222,12 +222,31 @@ describe('the one-time clone notice', () => {expect(text).toContain(PROJECT_CAPABILITY_COPY.agentMessaging.description)// Unanswered = refused: the exact predicate messagingEnabled consults.expect(- projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), 'agentMessaging')+ projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), 'agentMessaging', {})+ ).toBe(false)+ // …and a machine default that is ON does not change that: an explicit `true` from a clone still+ // needs this machine's answer, whatever the default says.+ expect(+ projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), 'agentMessaging', {+ agentMessagingDefault: true+ })).toBe(false)act(() => button('Turn it off').click())const p = useProjects.getState().getProject('p1')!- expect(p.agentMessaging).toBeUndefined()+ // Messaging has a machine default, so "off" is WRITTEN — an absent field would mean "use the+ // default", and a default that is on would undo the answer the user just gave.+ expect(p.agentMessaging).toBe(false)expect(p.capabilityAck).toEqual({ agentMessaging: 'declined' })+ expect(+ projectCapabilityGrantedFor(p, 'agentMessaging', { agentMessagingDefault: true })+ ).toBe(false)+ })++ it('a project that is on only by this machine’s default raises NO notice', () => {+ // Nothing arrived from a stranger: the file says nothing, the answer is this machine's own.+ useProjects.setState({ projects: [project()], activeProjectId: 'p1' })+ mount()+ expect(dialog()).toBeNull()})it('stays silent when the switch is off', () => {diff --git a/src/renderer/components/settings/agents-capabilities.test.tsx b/src/renderer/components/settings/agents-capabilities.test.tsxindex f79c23d5c..c710c652a 100644--- a/src/renderer/components/settings/agents-capabilities.test.tsx+++ b/src/renderer/components/settings/agents-capabilities.test.tsx@@ -11,10 +11,13 @@ import type { Project } from '@shared/types'import {PROJECT_CAPABILITIES,PROJECT_CAPABILITY_COPY,+ capabilityHasMachineDefault,projectCapabilityFlagInFile} from '@shared/project-capabilities'import { projectCapabilityGrantedFor } from '@shared/project-capability-consent'+import { DEFAULT_SETTINGS } from '@shared/types'import { useProjects } from '../../state/projects'+import { useSettings } from '../../state/settings'import { AgentsSection } from './sections/AgentsSection';(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true@@ -38,6 +41,32 @@ function mount(): void {act(() => root.render(<AgentsSection isActive />))}+/** Capabilities drawn as a two-position switch (no machine default) and as a three-way choice. */+const SWITCH_CAPS = PROJECT_CAPABILITIES.filter((c) => !capabilityHasMachineDefault(c))+const CHOICE_CAPS = PROJECT_CAPABILITIES.filter((c) => capabilityHasMachineDefault(c))++function capChoice(label: string): HTMLSelectElement {+ const el = host.querySelector<HTMLSelectElement>(`select[aria-label="${label}"]`)+ expect(el, `a rendered choice for "${label}"`).toBeTruthy()+ return el!+}++function choose(el: HTMLSelectElement, value: string): void {+ act(() => {+ el.value = value+ el.dispatchEvent(new Event('change', { bubbles: true }))+ })+}++/** Either control, for assertions that hold for both. */+function capControl(label: string): HTMLElement {+ const el =+ host.querySelector<HTMLElement>(`[role="switch"][aria-label="${label}"]`) ??+ host.querySelector<HTMLElement>(`select[aria-label="${label}"]`)+ expect(el, `a rendered control for "${label}"`).toBeTruthy()+ return el!+}+function capSwitch(label: string): HTMLElement {const el = host.querySelector<HTMLElement>(`[role="switch"][aria-label="${label}"]`)expect(el, `a rendered switch for "${label}"`).toBeTruthy()@@ -50,6 +79,7 @@ beforeEach(() => {claude: { cliCaps: vi.fn(async () => null) }}useProjects.setState({ projects: [project()], activeProjectId: 'p1', reloadNonce: 0 })+ useSettings.setState({ settings: DEFAULT_SETTINGS, hydrated: true })})afterEach(() => {@@ -64,7 +94,7 @@ describe('per-project capability rows, generated from PROJECT_CAPABILITIES', ()const text = host.textContent ?? ''for (const cap of PROJECT_CAPABILITIES) {const copy = PROJECT_CAPABILITY_COPY[cap]- capSwitch(copy.label)+ capControl(copy.label)expect(text).toContain(copy.description)// The same "this is in the project file" sentence the clone notice shows: the two// git-shared grants read alike wherever the switch is set.@@ -73,7 +103,7 @@ describe('per-project capability rows, generated from PROJECT_CAPABILITIES', ()expect(text).toContain('my-canvas')})- it.each([...PROJECT_CAPABILITIES])(+ it.each([...SWITCH_CAPS])('toggling %s on writes the literal true the strict validators accept, plus this machine’s ack',(cap) => {mount()@@ -86,7 +116,7 @@ describe('per-project capability rows, generated from PROJECT_CAPABILITIES', ()})- it.each([...PROJECT_CAPABILITIES])(+ it.each([...SWITCH_CAPS])('toggling %s off deletes the field outright — no bytes, and never a stored false',(cap) => {useProjects.getState().setProjectCapability('p1', cap, true)@@ -104,10 +134,10 @@ describe('per-project capability rows, generated from PROJECT_CAPABILITIES', ()// PR 6 Task 6.4 depends on this shape: the browser ledger / messagingEnabled read the switch// per call. Simulate two consecutive calls around an off-toggle and require the second to see// the refusal immediately — no lease-start snapshot may answer for it.- const cap = PROJECT_CAPABILITIES[0]+ const cap = SWITCH_CAPS[0]useProjects.getState().setProjectCapability('p1', cap, true)const grantedNow = (): boolean =>- projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), cap)+ projectCapabilityGrantedFor(useProjects.getState().getProject('p1'), cap, {})expect(grantedNow()).toBe(true)mount()act(() => capSwitch(PROJECT_CAPABILITY_COPY[cap].label).click())@@ -118,8 +148,68 @@ describe('per-project capability rows, generated from PROJECT_CAPABILITIES', ()useProjects.setState({ projects: [], activeProjectId: '' })mount()for (const cap of PROJECT_CAPABILITIES) {- const el = capSwitch(PROJECT_CAPABILITY_COPY[cap].label)+ const el = capControl(PROJECT_CAPABILITY_COPY[cap].label)expect(el.getAttribute('aria-disabled') === 'true' || el.hasAttribute('disabled')).toBe(true)}})})++describe('a capability with a machine default is a three-way choice, not a switch', () => {+ it('has one (agent messaging), and nothing without a default grew a choice', () => {+ expect(CHOICE_CAPS).toEqual(['agentMessaging'])+ })++ it.each([...CHOICE_CAPS])('%s: an untouched project reads "use default" and says it is off by default', (cap) => {+ mount()+ const el = capChoice(PROJECT_CAPABILITY_COPY[cap].label)+ expect(el.value).toBe('default')+ expect(host.textContent).toContain("Off in my-canvas (this machine's default).")+ expect(el.textContent).toContain("Use this machine's default (off)")+ })++ it.each([...CHOICE_CAPS])('%s: with the machine default ON, an untouched project reads "on (default)" and GRANTS', (cap) => {+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, agentMessagingDefault: true }, hydrated: true })+ mount()+ expect(capChoice(PROJECT_CAPABILITY_COPY[cap].label).value).toBe('default')+ expect(host.textContent).toContain("On in my-canvas (this machine's default).")+ const p = useProjects.getState().getProject('p1')+ expect(projectCapabilityGrantedFor(p, cap, useSettings.getState().settings)).toBe(true)+ // …and nothing was written to the project to make it so.+ expect(p && Object.prototype.hasOwnProperty.call(p, cap)).toBe(false)+ })++ it.each([...CHOICE_CAPS])('%s: "On" writes true + kept; "Off" writes an explicit false + declined that beats a default', (cap) => {+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, agentMessagingDefault: true }, hydrated: true })+ mount()+ choose(capChoice(PROJECT_CAPABILITY_COPY[cap].label), 'on')+ let p = useProjects.getState().getProject('p1')!+ expect(p[cap]).toBe(true)+ expect(p.capabilityAck?.[cap]).toBe('kept')+ expect(host.textContent).toContain('On in my-canvas (set for this project).')+ choose(capChoice(PROJECT_CAPABILITY_COPY[cap].label), 'off')+ p = useProjects.getState().getProject('p1')!+ expect(p[cap]).toBe(false)+ expect(p.capabilityAck?.[cap]).toBe('declined')+ expect(projectCapabilityGrantedFor(p, cap, useSettings.getState().settings)).toBe(false)+ expect(host.textContent).toContain('Off in my-canvas (set for this project).')+ })++ it.each([...CHOICE_CAPS])('%s: "Use default" clears the value AND the answer, so the default applies again', (cap) => {+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, agentMessagingDefault: true }, hydrated: true })+ useProjects.getState().setProjectCapability('p1', cap, false)+ mount()+ choose(capChoice(PROJECT_CAPABILITY_COPY[cap].label), 'default')+ const p = useProjects.getState().getProject('p1')!+ expect(Object.prototype.hasOwnProperty.call(p, cap)).toBe(false)+ expect(p.capabilityAck?.[cap]).toBeUndefined()+ expect(projectCapabilityGrantedFor(p, cap, useSettings.getState().settings)).toBe(true)+ })++ it('the machine default is a switch in settings.json, not in any project', () => {+ mount()+ const label = 'Agent messaging in projects that do not set it'+ act(() => capSwitch(label).click())+ expect(useSettings.getState().settings.agentMessagingDefault).toBe(true)+ expect(Object.prototype.hasOwnProperty.call(useProjects.getState().getProject('p1')!, 'agentMessaging')).toBe(false)+ })+})diff --git a/src/renderer/components/settings/sections/AgentsSection.tsx b/src/renderer/components/settings/sections/AgentsSection.tsxindex df18c097d..edb182450 100644--- a/src/renderer/components/settings/sections/AgentsSection.tsx+++ b/src/renderer/components/settings/sections/AgentsSection.tsx@@ -5,8 +5,17 @@ import { useBrowserLease, drivingNodeIds } from '../../../state/browserLease'import {PROJECT_CAPABILITIES,PROJECT_CAPABILITY_COPY,+ capabilityHasMachineDefault,+ capabilityMachineDefault,projectCapabilityFlagInFile} from '@shared/project-capabilities'+import {+ applyCapabilityChoice,+ capabilityChoiceLabel,+ capabilityChoiceOf,+ capabilityStatusText,+ type CapabilityChoice+} from '../../../lib/capabilityChoice'import {isAgentEnabled,setAgentEnabled,@@ -92,6 +101,10 @@ const ROWS = {'clear env']},+ messagingDefault: {+ title: 'Agent messaging in projects that do not set it',+ keywords: ['agent', 'message', 'messaging', 'default', 'project', 'send', 'reply', 'orchestration']+ },permissionMode: {title: 'Permission mode',keywords: [@@ -217,6 +230,7 @@ const CAPABILITY_ROWS = PROJECT_CAPABILITIES.map((cap) => ({...PROJECT_CAPABILITY_COPY[cap].label.toLowerCase().split(/\s+/)]}))+const CAPABILITY_CHOICES: readonly CapabilityChoice[] = ['default', 'on', 'off']const ENTRIES = [...Object.values(ROWS),...CAPABILITY_ROWS.map(({ title, keywords }) => ({ title, keywords }))@@ -366,6 +380,7 @@ export function AgentsSection({ isActive }: { isActive: boolean }): React.JSX.Elconst activeProjectId = useProjects((s) => s.activeProjectId)const activeProject = useProjects((s) => s.projects.find((p) => p.id === activeProjectId))const setProjectCapability = useProjects((s) => s.setProjectCapability)+ const resetProjectCapabilityToDefault = useProjects((s) => s.resetProjectCapabilityToDefault)// The kill row (Task 6.4): browser nodes an agent is driving RIGHT NOW, across every open project,// each with a Stop and one Stop-all. The precedent is the identity escape hatch — a user who// notices their browser doing something needs one obvious place to end it, not a per-node hunt.@@ -725,44 +740,91 @@ export function AgentsSection({ isActive }: { isActive: boolean }): React.JSX.El)}</div></SearchableRow>- {CAPABILITY_ROWS.map(({ cap, title, keywords }) => (- <SearchableRow key={cap} title={title} keywords={keywords}>- <FieldRow- label={title}- note={- activeProject- ? `Applies to the active project: ${activeProject.name}.`- : 'Open a project to change this — the switch belongs to a project, not to the app.'- }- // The description carries the capability's own copy AND its cloneWarning — the same- // "this is in the project file" sentence the clone notice shows, so the two git-shared- // grants read alike wherever they appear (pinned by agents-capabilities.test.tsx).- description={`${PROJECT_CAPABILITY_COPY[cap].description} ${PROJECT_CAPABILITY_COPY[cap].cloneWarning}`}- control={- <Switch- // The raw FILE FLAG is the right thing for a settings switch to display — it- // mirrors what is written in .nodeterm/project.json. It is NEVER the grant check:- // grants require the machine-local 'kept' too (projectCapabilityGrantedFor).- checked={projectCapabilityFlagInFile(activeProject, cap)}- ariaLabel={title}- disabled={!activeProject}- onChange={(on) => {- // The ONE strict setter: literal `true` on, field deleted on off. Writing the- // value any other way (a string, a stored false) is the bug the validators- // exist to refuse.- if (activeProject) setProjectCapability(activeProject.id, cap, on)- // Turning browser control OFF revokes any live lease in this project immediately- // (Task 6.4) — detach now, don't wait for the next drive to read the switch. Read- // live off this toggle, never cached at lease start.- if (activeProject && cap === 'agentBrowserControl' && !on) {- window.nodeTerminal?.browser?.stopProject?.(activeProject.id)- }- }}- />- }- />- </SearchableRow>- ))}+ <SearchableRow {...ROWS.messagingDefault}>+ <FieldRow+ label={ROWS.messagingDefault.title}+ description="What agent messaging does in a project whose settings do not say. It is stored on this computer only, never in a project file: a project set to on or off keeps its own setting, and a project file that turns messaging on still asks you to confirm it before it takes effect here."+ control={+ <Switch+ checked={settings.agentMessagingDefault === true}+ ariaLabel={ROWS.messagingDefault.title}+ onChange={(on) => update({ agentMessagingDefault: on })}+ />+ }+ />+ </SearchableRow>+ {CAPABILITY_ROWS.map(({ cap, title, keywords }) =>+ capabilityHasMachineDefault(cap) ? (+ // A capability with a machine default has THREE file states (on / off / use default), so+ // it is a choice plus a sentence saying what is in effect — see lib/capabilityChoice.+ <SearchableRow key={cap} title={title} keywords={keywords}>+ <FieldRow+ label={title}+ note={capabilityStatusText(activeProject, cap, settings)}+ description={`${PROJECT_CAPABILITY_COPY[cap].description} ${PROJECT_CAPABILITY_COPY[cap].cloneWarning}`}+ control={+ <Select+ aria-label={title}+ disabled={!activeProject}+ value={capabilityChoiceOf(activeProject, cap)}+ onChange={(e) => {+ if (!activeProject) return+ applyCapabilityChoice(+ { setProjectCapability, resetProjectCapabilityToDefault },+ activeProject.id,+ cap,+ e.target.value as CapabilityChoice+ )+ }}+ >+ {CAPABILITY_CHOICES.map((c) => (+ <option key={c} value={c}>+ {capabilityChoiceLabel(c, capabilityMachineDefault(settings, cap))}+ </option>+ ))}+ </Select>+ }+ />+ </SearchableRow>+ ) : (+ <SearchableRow key={cap} title={title} keywords={keywords}>+ <FieldRow+ label={title}+ note={+ activeProject+ ? `Applies to the active project: ${activeProject.name}.`+ : 'Open a project to change this — the switch belongs to a project, not to the app.'+ }+ // The description carries the capability's own copy AND its cloneWarning — the same+ // "this is in the project file" sentence the clone notice shows, so the two git-shared+ // grants read alike wherever they appear (pinned by agents-capabilities.test.tsx).+ description={`${PROJECT_CAPABILITY_COPY[cap].description} ${PROJECT_CAPABILITY_COPY[cap].cloneWarning}`}+ control={+ <Switch+ // The raw FILE FLAG is the right thing for a settings switch to display — it+ // mirrors what is written in .nodeterm/project.json. It is NEVER the grant check:+ // grants require the machine-local 'kept' too (projectCapabilityGrantedFor).+ checked={projectCapabilityFlagInFile(activeProject, cap)}+ ariaLabel={title}+ disabled={!activeProject}+ onChange={(on) => {+ // The ONE strict setter: literal `true` on, field deleted on off. Writing the+ // value any other way (a string, a stored false) is the bug the validators+ // exist to refuse.+ if (activeProject) setProjectCapability(activeProject.id, cap, on)+ // Turning browser control OFF revokes any live lease in this project immediately+ // (Task 6.4) — detach now, don't wait for the next drive to read the switch. Read+ // live off this toggle, never cached at lease start.+ if (activeProject && cap === 'agentBrowserControl' && !on) {+ window.nodeTerminal?.browser?.stopProject?.(activeProject.id)+ }+ }}+ />+ }+ />+ </SearchableRow>+ )+ )}<SearchableRow {...ROWS.hibernation}><FieldRowlabel="Hibernate idle agents"diff --git a/src/renderer/lib/capabilityChoice.ts b/src/renderer/lib/capabilityChoice.tsnew file mode 100644index 000000000..9263b844f--- /dev/null+++ b/src/renderer/lib/capabilityChoice.ts@@ -0,0 +1,80 @@+/**+ * The Settings → Agents view of a per-project capability that has a MACHINE DEFAULT+ * (@shared/project-capabilities, CAPABILITY_MACHINE_DEFAULTS — today only agent messaging).+ *+ * A capability with a default has THREE states in the project file, not two: an explicit `true`, an+ * explicit `false`, and absent ("use this machine's default"). A two-position switch cannot show+ * that — it would draw "off" for a project that is on by default, and toggling it would write an+ * explicit value the user never asked for — so these rows are a three-way choice plus one sentence+ * saying what is in effect and why. Pure so the wording and the mapping are tested without a DOM.+ */+import {+ projectCapabilityFileState,+ type CapabilityMachineDefaults,+ type ProjectCapability+} from '@shared/project-capabilities'+import {+ capabilityAnswerOf,+ projectCapabilityEffective,+ type CapabilityAckMap+} from '@shared/project-capability-consent'++export type CapabilityChoice = 'default' | 'on' | 'off'++type ProjectView = Partial<Record<ProjectCapability, unknown>> & {+ capabilityAck?: CapabilityAckMap+ name?: string+}++/** Which of the three choices the project currently holds. An absent value this machine DECLINED+ * reads as `off`, because that is what it is: the pre-default "turn it off" wrote exactly that. */+export function capabilityChoiceOf(+ p: ProjectView | undefined,+ cap: ProjectCapability+): CapabilityChoice {+ const file = projectCapabilityFileState(p, cap)+ if (file === 'on') return 'on'+ if (file === 'off') return 'off'+ return capabilityAnswerOf(p, cap) === 'declined' ? 'off' : 'default'+}++export function capabilityChoiceLabel(choice: CapabilityChoice, machineDefaultOn: boolean): string {+ if (choice === 'on') return 'On in this project'+ if (choice === 'off') return 'Off in this project'+ return `Use this machine's default (${machineDefaultOn ? 'on' : 'off'})`+}++/** One sentence: what is in effect for the project right now, and where that came from. */+export function capabilityStatusText(+ p: ProjectView | undefined,+ cap: ProjectCapability,+ defaults: CapabilityMachineDefaults+): string {+ if (!p) return 'Open a project to change this — the switch belongs to a project, not to the app.'+ const name = p.name ?? 'this project'+ const effective = projectCapabilityEffective(p, cap, defaults)+ if (effective.pendingNotice) {+ return (+ `Off in ${name} for now: its project file turns it on, but you have not confirmed that on ` ++ 'this machine yet. Choose "On in this project" to confirm it.'+ )+ }+ const state = effective.on ? 'On' : 'Off'+ const why = effective.source === 'default' ? "this machine's default" : 'set for this project'+ return `${state} in ${name} (${why}).`+}++export interface CapabilityChoiceWriters {+ setProjectCapability(id: string, cap: ProjectCapability, on: boolean): void+ resetProjectCapabilityToDefault(id: string, cap: ProjectCapability): void+}++export function applyCapabilityChoice(+ writers: CapabilityChoiceWriters,+ projectId: string,+ cap: ProjectCapability,+ choice: CapabilityChoice+): void {+ if (choice === 'default') writers.resetProjectCapabilityToDefault(projectId, cap)+ else writers.setProjectCapability(projectId, cap, choice === 'on')+}diff --git a/src/renderer/lib/controlRouting.ts b/src/renderer/lib/controlRouting.tsindex ae38a576a..539a6195d 100644--- a/src/renderer/lib/controlRouting.ts+++ b/src/renderer/lib/controlRouting.ts@@ -156,7 +156,9 @@ export function answerBrowserResolve(// LIVE read — the drive-time capability check the whole feature's safety rests on. A project.json// hand-edit that flipped the switch off is reflected here the next time an agent drives, which is// exactly drive time.- capabilityOn: projectCapabilityGrantedFor(project, 'agentBrowserControl'),+ // `{}`: browser control has no machine default (CAPABILITY_MACHINE_DEFAULTS) — an absent switch is+ // off, and no setting on this machine can change that.+ capabilityOn: projectCapabilityGrantedFor(project, 'agentBrowserControl', {}),sourceTitle: typeof node.title === 'string' ? node.title : '',browserTitle: typeof browserNode?.title === 'string' ? browserNode.title : ''}diff --git a/src/renderer/lib/settingsVerb.test.ts b/src/renderer/lib/settingsVerb.test.tsindex f9d50b0d7..eeaef2bc4 100644--- a/src/renderer/lib/settingsVerb.test.ts+++ b/src/renderer/lib/settingsVerb.test.ts@@ -55,7 +55,7 @@ describe('a CLI change lands as exactly the state the Settings switch produces',expect(strip(cli)).toEqual(strip(ui))expect(projectCapabilityFlagInFile(cli, 'agentMessaging')).toBe(true)expect(capabilityAnswerOf(cli, 'agentMessaging')).toBe('kept')- expect(projectCapabilityGrantedFor(cli, 'agentMessaging')).toBe(true)+ expect(projectCapabilityGrantedFor(cli, 'agentMessaging', {})).toBe(true)expect(needsCapabilityNotice({capability: 'agentMessaging',@@ -76,7 +76,7 @@ describe('a CLI change lands as exactly the state the Settings switch produces',expect(strip(useProjects.getState().getProject('cli')!)).toEqual(strip(useProjects.getState().getProject('ui')!))- expect(projectCapabilityGrantedFor(useProjects.getState().getProject('cli'), 'agentMessaging')).toBe(true)+ expect(projectCapabilityGrantedFor(useProjects.getState().getProject('cli'), 'agentMessaging', {})).toBe(true)})it('turning it OFF matches too', () => {@@ -86,7 +86,7 @@ describe('a CLI change lands as exactly the state the Settings switch produces',expect(strip(useProjects.getState().getProject('cli')!)).toEqual(strip(useProjects.getState().getProject('ui')!))- expect(projectCapabilityGrantedFor(useProjects.getState().getProject('cli'), 'agentMessaging')).toBe(false)+ expect(projectCapabilityGrantedFor(useProjects.getState().getProject('cli'), 'agentMessaging', {})).toBe(false)})})@@ -98,3 +98,29 @@ describe('applySettingsChange writes through exactly one setter', () => {expect(writers.setProjectCapability).not.toHaveBeenCalled()})})++describe('under a machine default that is ON, the CLI and the Settings choice still land identically', () => {+ it('--set false writes the same explicit false + declined as choosing "Off in this project"', () => {+ useProjects.getState().hydrate({+ version: 2,+ activeProjectId: 'cli',+ projects: [base('cli'), base('ui')]+ })+ const settings = { ...DEFAULT_SETTINGS, agentMessagingDefault: true }+ const request = parseSettingsRequest({ set: 'agentMessaging', value: 'false' })+ if ('error' in request || request.action !== 'set') throw new Error('bad request')+ const plan = planSettingsSet({+ request,+ settings,+ project: useProjects.getState().getProject('cli'),+ requestedBy: 'agent'+ })+ if (plan.kind !== 'confirm') throw new Error(`expected a confirm, got ${plan.kind}`)+ applySettingsChange(plan.change)+ useProjects.getState().setProjectCapability('ui', 'agentMessaging', false)+ const cli = useProjects.getState().getProject('cli')!+ expect(strip(cli)).toEqual(strip(useProjects.getState().getProject('ui')!))+ expect(cli.agentMessaging).toBe(false)+ expect(projectCapabilityGrantedFor(cli, 'agentMessaging', settings)).toBe(false)+ })+})diff --git a/src/renderer/state/projects.ts b/src/renderer/state/projects.tsindex 79ada0201..5de7eb695 100644--- a/src/renderer/state/projects.ts+++ b/src/renderer/state/projects.ts@@ -13,7 +13,7 @@ import type {} from '@shared/types'import { CLOSED_SESSIONS_CAP } from '@shared/types'import { collisionSeed, derivedProjectId } from '@shared/project-id'-import type { ProjectCapability } from '@shared/project-capabilities'+import { capabilityHasMachineDefault, type ProjectCapability } from '@shared/project-capabilities'import type { ProjectIcon } from '@shared/project-icon'import { recordCapabilityAck, type CapabilityAnswer } from '@shared/project-capability-consent'import {@@ -101,10 +101,19 @@ interface ProjectsState {* THE strict per-project capability setter (@shared/project-capabilities). `on` writes the* literal `true` the validators accept AND records this machine's 'kept' answer — setting a* switch yourself is its own consent, so the clone notice never fires on your own decision.- * `off` deletes the field outright (an off capability adds no bytes to the shared file) AND- * records 'declined': if a teammate's (or a hostile) `true` re-arrives via git, the capability- * is refused and re-noticed rather than silently re-granted (PR #213 C1/M-2). */+ * `off` deletes the field (an off capability adds no bytes to the shared file) — EXCEPT for a+ * capability with a machine default (CAPABILITY_MACHINE_DEFAULTS), where absence means "use this+ * machine's default" and off must therefore be written as a literal `false`. Either way it records+ * 'declined': if a teammate's (or a hostile) `true` re-arrives via git, the capability is refused+ * and re-noticed rather than silently re-granted (PR #213 C1/M-2). */setProjectCapability(id: string, cap: ProjectCapability, on: boolean): void+ /**+ * "Use this machine's default" — only meaningful for a capability with a machine default. Removes+ * the file's value AND this machine's recorded answer for it: a kept `'declined'` would otherwise+ * keep an absent field off (the rule that protects a pre-default "turn it off"), so the choice the+ * user just made would not take effect. If a `true` later re-arrives via git it meets no answer+ * and raises the clone notice, exactly as for a never-configured project. */+ resetProjectCapabilityToDefault(id: string, cap: ProjectCapability): void/*** Records this machine's ANSWER ('kept' | 'declined') to the one-time clone notice.* MACHINE-LOCAL by construction: `Project.capabilityAck` rides `IndexEntryV3.capabilityAck`@@ -472,7 +481,8 @@ export const useProjects = create<ProjectsState>((set, get) => ({if (p.id !== id) return pif (on) return recordCapabilityAck({ ...p, [cap]: true }, cap, 'kept')const next = { ...p }- delete next[cap]+ if (capabilityHasMachineDefault(cap)) next[cap] = false+ else delete next[cap]// 'declined', not silence: the deletion lives only in this working copy, so a re-arriving// `true` (teammate commit, git checkout) must re-notice instead of meeting a bare ack.return recordCapabilityAck(next, cap, 'declined')@@ -484,6 +494,25 @@ export const useProjects = create<ProjectsState>((set, get) => ({markWorkspaceDirty()},+ resetProjectCapabilityToDefault(id, cap) {+ if (!capabilityHasMachineDefault(cap)) return+ set((s) => ({+ projects: s.projects.map((p) => {+ if (p.id !== id) return p+ const next = { ...p }+ delete next[cap]+ if (next.capabilityAck && Object.prototype.hasOwnProperty.call(next.capabilityAck, cap)) {+ const ack = { ...next.capabilityAck }+ delete ack[cap]+ if (Object.keys(ack).length) next.capabilityAck = ack+ else delete next.capabilityAck+ }+ return next+ })+ }))+ markWorkspaceDirty()+ },+recordProjectCapabilityAck(id, cap, answer) {set((s) => ({projects: s.projects.map((p) => (p.id === id ? recordCapabilityAck(p, cap, answer) : p))diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.tsindex bc2a3593e..82735cfa3 100644--- a/src/server/canvas-control.ts+++ b/src/server/canvas-control.ts@@ -196,8 +196,11 @@ export async function initServerCanvasControl(mirrorEntry,projects: () => deps.workspaceStore.persistedCanvases(),isRemoteNode: () => false,- messagingEnabled: messagingEnabledVia((projectId) =>- deps.workspaceStore.capabilityProjectFor(projectId)),+ messagingEnabled: messagingEnabledVia(+ (projectId) => deps.workspaceStore.capabilityProjectFor(projectId),+ // The SAME machine default the desktop reads — this shell's own settings.json.+ () => deps.settings()+ ),paneOwnerProject,callerOwnsTarget: (sourceNodeId, targetNodeId) =>factory.ownsSpawn(sourceNodeId, targetNodeId),diff --git a/src/server/settings-control.ts b/src/server/settings-control.tsindex ddca8cfce..291957a0f 100644--- a/src/server/settings-control.ts+++ b/src/server/settings-control.ts@@ -39,7 +39,7 @@ export interface ServerSettingsControlDeps {persistedCanvases(): Array<{ id: string; nodes: ReadonlyArray<{ id: string }> }>capabilityProjectFor(projectId: string- ): (Partial<Record<ProjectCapability, true>> & { capabilityAck?: CapabilityAckMap }) | undefined+ ): (Partial<Record<ProjectCapability, boolean>> & { capabilityAck?: CapabilityAckMap }) | undefinedprojectName(projectId: string): string | undefinedsettings(): Settings}diff --git a/src/shared/project-capabilities.ts b/src/shared/project-capabilities.tsindex 4ee23ccae..4fb46154a 100644--- a/src/shared/project-capabilities.ts+++ b/src/shared/project-capabilities.ts@@ -21,7 +21,25 @@** If (2) is ever dropped as friction, this field must move to a machine-local store. That is the* trigger, written down where the decision is, not only in the design doc.+ *+ * ── MACHINE DEFAULTS (agentMessaging only) ──────────────────────────────────────────────────────+ * A capability may name a MACHINE-LOCAL default in settings.json (`CAPABILITY_MACHINE_DEFAULTS`)+ * that answers for a project whose file carries NO value. This does not trip the trigger above,+ * and the reason is the whole design: (2) is not dropped — a literal `true` in the file still+ * grants only with this machine's `'kept'` answer, so a stranger's `true` still raises the notice.+ * What the default decides is ABSENCE, and absence is not something a clone can hand anyone: the+ * value that answers it lives in this machine's own settings.json, set by this machine's user. A+ * hostile repo can at most OMIT the field, which yields exactly what the user already chose for+ * every project they did not configure.+ *+ * Absence therefore stops meaning "off" for such a capability, so OFF has to be written: the file+ * carries a literal `false` (`projectCapabilityFileState` → `'off'`), which beats any default. And a+ * recorded `'declined'` keeps an absent field off too — that is how every pre-default build wrote+ * "turn it off" (delete the field + decline), and a user's explicit no must not be undone by a+ * default they turned on later.*/+import type { Settings } from './types'+export type ProjectCapability = 'agentBrowserControl' | 'agentMessaging'export const PROJECT_CAPABILITIES: readonly ProjectCapability[] = [@@ -66,6 +84,48 @@ export const PROJECT_CAPABILITY_COPY: Record<ProjectCapability, ProjectCapabilit}}+/**+ * Capabilities whose ABSENT file value is answered by a machine-local setting, and which setting.+ * Only these may carry a literal `false` in the file — for every other capability off is still+ * "no field", byte-identical to before.+ */+export const CAPABILITY_MACHINE_DEFAULTS: Partial<+ Record<ProjectCapability, keyof Pick<Settings, 'agentMessagingDefault'>>+> = {+ agentMessaging: 'agentMessagingDefault'+}++export function capabilityHasMachineDefault(cap: ProjectCapability): boolean {+ return Object.prototype.hasOwnProperty.call(CAPABILITY_MACHINE_DEFAULTS, cap)+}++/** The machine-local defaults a grant check needs — `settings.json`, read STRICTLY (`=== true`):+ * the file is hand-editable, and `"true"` there must not turn a capability on everywhere. */+export type CapabilityMachineDefaults = Partial<Pick<Settings, 'agentMessagingDefault'>>++export function capabilityMachineDefault(+ defaults: CapabilityMachineDefaults | undefined | null,+ cap: ProjectCapability+): boolean {+ const key = CAPABILITY_MACHINE_DEFAULTS[cap]+ return !!key && defaults?.[key] === true+}++/** What the shared file says: a literal `true` (`on`), a literal `false` on a capability that has a+ * machine default (`off`), or nothing usable (`absent`). Own properties only; every other value —+ * `"true"`, `1`, a `false` on a capability without a default — is `absent`. */+export type CapabilityFileState = 'on' | 'off' | 'absent'++export function projectCapabilityFileState(+ p: Partial<Record<ProjectCapability, unknown>> | undefined | null,+ cap: ProjectCapability+): CapabilityFileState {+ if (!p || !Object.prototype.hasOwnProperty.call(p, cap)) return 'absent'+ if (p[cap] === true) return 'on'+ if (p[cap] === false && capabilityHasMachineDefault(cap)) return 'off'+ return 'absent'+}+/*** Is the capability's raw switch set in this project's shared file? STRICT `=== true`, own* properties only: .nodeterm/project.json is hostile input — git-shared, hand-editable,@@ -87,25 +147,24 @@ export function projectCapabilityFlagInFile(return p[cap] === true}-/** The capability half of a ProjectFileV1, normalised: known keys only, literal `true` only,- * own properties only (M-1: no consent inherited through a prototype chain). */-export function readProjectCapabilities(f: unknown): Partial<Record<ProjectCapability, true>> {- const out: Partial<Record<ProjectCapability, true>> = {}+/** The capability half of a ProjectFileV1, normalised: known keys only, own properties only (M-1:+ * no consent inherited through a prototype chain), literal `true` — plus a literal `false` for a+ * capability with a machine default, where off must be written to beat that default. */+export function readProjectCapabilities(f: unknown): Partial<Record<ProjectCapability, boolean>> {+ const out: Partial<Record<ProjectCapability, boolean>> = {}if (!f || typeof f !== 'object') return outfor (const cap of PROJECT_CAPABILITIES) {- if (- Object.prototype.hasOwnProperty.call(f, cap) &&- (f as Record<string, unknown>)[cap] === true- )- out[cap] = true+ const state = projectCapabilityFileState(f as Partial<Record<ProjectCapability, unknown>>, cap)+ if (state === 'on') out[cap] = true+ else if (state === 'off') out[cap] = false}return out}-/** The spread `projectToFile` uses. Absent keys are omitted, so an off capability adds no bytes to- * the committed file and no churn to anyone's git diff. */+/** The spread `projectToFile` uses. Absent keys are omitted, so a capability without a machine+ * default adds no bytes when off; one WITH a default writes its explicit `false`. */export function projectCapabilityFields(p: Partial<Record<ProjectCapability, unknown>> | undefined | null-): Partial<Record<ProjectCapability, true>> {+): Partial<Record<ProjectCapability, boolean>> {return readProjectCapabilities(p ?? {})}diff --git a/src/shared/project-capability-consent.ts b/src/shared/project-capability-consent.tsindex 134c1e10a..6e12407a0 100644--- a/src/shared/project-capability-consent.ts+++ b/src/shared/project-capability-consent.ts@@ -26,7 +26,10 @@* callers, and its test pins that the two paths are the same function objects.*/import {- projectCapabilityFlagInFile,+ capabilityHasMachineDefault,+ capabilityMachineDefault,+ projectCapabilityFileState,+ type CapabilityMachineDefaults,type ProjectCapability} from './project-capabilities'@@ -67,24 +70,67 @@ export function projectCapabilityGranted(s: CapabilityConsentState): boolean {return s.enabledInFile === true && s.answer === 'kept'}+/** Where an effective capability value came from — for display, never for a grant decision. */+export type CapabilitySource = 'project' | 'default'++export interface CapabilityEffective {+ /** THE grant. */+ on: boolean+ /** `project` = the file carries an explicit value (or this machine declined it); `default` = the+ * file says nothing and this machine's setting answered. */+ source: CapabilitySource+ /** The file says `true` but this machine has not KEPT it: off, and the clone notice is owed. */+ pendingNotice: boolean+}++/**+ * The whole grant rule, ONCE — every consumer reads it through here or `projectCapabilityGrantedFor`+ * so no consumer invents its own default:+ * - file `true` → granted only with this machine's `'kept'` (unchanged: a clone's `true` notices)+ * - file `false` → off, whatever the default (the explicit value always wins)+ * - absent → a recorded `'declined'` keeps it off (the pre-default builds wrote "off" as a+ * deleted field + decline); otherwise the MACHINE-LOCAL default answers, and only+ * for a capability that has one (`CAPABILITY_MACHINE_DEFAULTS`).+ * `needsCapabilityNotice` is deliberately untouched: it stays keyed on an EXPLICIT `true`, so a+ * project that is on only by this machine's default never raises a notice (nothing arrived from a+ * stranger) while a cloned `true` always does. Pinned by project-capability-consent.test.ts.+ */+export function projectCapabilityEffective(+ p:+ | (Partial<Record<ProjectCapability, unknown>> & { capabilityAck?: CapabilityAckMap })+ | undefined+ | null,+ cap: ProjectCapability,+ defaults: CapabilityMachineDefaults+): CapabilityEffective {+ const file = projectCapabilityFileState(p, cap)+ const answer = capabilityAnswerOf(p, cap)+ if (file === 'on') {+ const on = projectCapabilityGranted({ capability: cap, enabledInFile: true, answer })+ return { on, source: 'project', pendingNotice: !on }+ }+ if (file === 'off' || !capabilityHasMachineDefault(cap) || answer === 'declined') {+ return { on: false, source: 'project', pendingNotice: false }+ }+ return { on: capabilityMachineDefault(defaults, cap), source: 'default', pendingNotice: false }+}+/**- * THE consumer-facing grant check: derives both halves (strict file flag, own-property answer)- * from a Project-shaped object, so a consumer cannot pick the raw file flag by mistake (PR #213- * review, I2). PR 6 wires `messagingEnabled(projectId)` as- * `projectCapabilityGrantedFor(getProject(projectId), 'agentMessaging')` — one call, nothing else.+ * THE consumer-facing grant check: derives every half (the file's value, this machine's+ * own-property answer, this machine's default) from a Project-shaped object and the settings, so a+ * consumer cannot pick the raw file flag by mistake (PR #213 review, I2). `defaults` is REQUIRED —+ * a consumer that forgot the machine default must fail to compile, not silently read it as off+ * while every other surface reads it as on.*/export function projectCapabilityGrantedFor(p:| (Partial<Record<ProjectCapability, unknown>> & { capabilityAck?: CapabilityAckMap })| undefined| null,- cap: ProjectCapability+ cap: ProjectCapability,+ defaults: CapabilityMachineDefaults): boolean {- return projectCapabilityGranted({- capability: cap,- enabledInFile: projectCapabilityFlagInFile(p, cap),- answer: capabilityAnswerOf(p, cap)- })+ return projectCapabilityEffective(p, cap, defaults).on}/** This machine's recorded answer, own properties only (M-1: an in-process object must not inheritdiff --git a/src/shared/settings-verb.test.ts b/src/shared/settings-verb.test.tsindex 0de7f581f..c1f9473cc 100644--- a/src/shared/settings-verb.test.ts+++ b/src/shared/settings-verb.test.ts@@ -39,7 +39,8 @@ describe('the allowlist is the gate, and the forbidden set outranks it', () => {'telemetryEnabled','keybindings','controlConfirmWaivers',- 'capabilityAck'+ 'capabilityAck',+ 'agentMessagingDefault']) {expect((SETTINGS_VERB_FORBIDDEN as ReadonlySet<string>).has(key), key).toBe(true)}@@ -229,3 +230,51 @@ describe('planSettingsSet', () => {expect(plan.danger).toBe(false)})})++describe('agentMessaging under the MACHINE DEFAULT', () => {+ const on = { ...DEFAULT_SETTINGS, agentMessagingDefault: true }+ it('reads "on (this machine\'s default)" for a project whose file says nothing', () => {+ expect(readSettingsValue('agentMessaging', on, project())).toMatchObject({+ value: true,+ display: "on (this machine's default)"+ })+ expect(readSettingsValue('agentMessaging', DEFAULT_SETTINGS, project())).toMatchObject({+ value: false,+ display: "off (this machine's default)"+ })+ })+ it('an explicit value reads as the project\'s own', () => {+ expect(+ readSettingsValue('agentMessaging', on, project({ agentMessaging: false }))+ ).toMatchObject({ value: false, display: 'off (this project)' })+ })+ it('--set true on a project already on by default changes nothing, and says why', () => {+ const plan = planSettingsSet({+ request: { action: 'set', key: 'agentMessaging', value: true },+ settings: on,+ project: project(),+ requestedBy: 'a'+ })+ expect(plan).toEqual({+ kind: 'unchanged',+ message: expect.stringContaining("already on (this machine's default)")+ })+ })+ it('--set false on a project on by default asks, and turns it off for this project', () => {+ const plan = planSettingsSet({+ request: { action: 'set', key: 'agentMessaging', value: false },+ settings: on,+ project: project(),+ requestedBy: 'a'+ })+ expect(plan).toMatchObject({+ kind: 'confirm',+ change: { scope: 'project', projectId: 'p1', capability: 'agentMessaging', on: false }+ })+ })+ it('the machine default itself can never be set from the CLI', () => {+ expect(parseSettingsRequest({ set: 'agentMessagingDefault', value: 'true' })).toEqual({+ error: expect.stringContaining('settings-key-forbidden: "agentMessagingDefault"')+ })+ })+})diff --git a/src/shared/settings-verb.ts b/src/shared/settings-verb.tsindex 55c6bba30..3f3b49e6c 100644--- a/src/shared/settings-verb.ts+++ b/src/shared/settings-verb.ts@@ -31,14 +31,10 @@* In `src/shared` because both edges need it: the desktop renderer (dispatch + dialog) and the* Server Edition's headless handler (`get`, plus the named `--set` refusal).*/-import {- PROJECT_CAPABILITY_COPY,- projectCapabilityFlagInFile,- type ProjectCapability-} from './project-capabilities'+import { PROJECT_CAPABILITY_COPY, type ProjectCapability } from './project-capabilities'import {capabilityAnswerOf,- projectCapabilityGrantedFor,+ projectCapabilityEffective,type CapabilityAckMap} from './project-capability-consent'import type { Project, Settings } from './types'@@ -66,6 +62,10 @@ type MachineKey = keyof Pick<>type ProjectKey = Extract<ProjectCapability, 'agentMessaging'>export type SettingsVerbKey = MachineKey | ProjectKey+/** What a reader needs from settings.json: the machine keys, plus the machine default a project+ * capability falls back to when its file says nothing. */+export type SettingsVerbSettings = Pick<Settings, MachineKey> &+ Partial<Pick<Settings, 'agentMessagingDefault'>>/*** THE ALLOWLIST. Order = the order `settings` lists them in.@@ -139,6 +139,9 @@ export const SETTINGS_VERB_FORBIDDEN = new Set<keyof Settings | keyof Project>(['customAgents','commitAgentCommand','defaultShell',+ // The machine default for messaging: a grant over EVERY project on this machine at once, cloned+ // ones included. The per-project switch is the narrower, confirmable thing an agent may ask for.+ 'agentMessagingDefault',// Telemetry.'telemetryEnabled',// Keybindings and the terminal-first shortcut policy.@@ -283,7 +286,7 @@ export interface SettingsValue {*/export function readSettingsValue(key: SettingsVerbKey,- settings: Pick<Settings, MachineKey>,+ settings: SettingsVerbSettings,project: SettingsProjectView | undefined): SettingsValue | { error: string } {const spec = SETTINGS_VERB_KEYS[key]@@ -295,22 +298,26 @@ export function readSettingsValue(return { error: `settings: ${key} belongs to a project, and this node is not in a saved project yet` }}const cap = key as ProjectCapability- const granted = projectCapabilityGrantedFor(project, cap)+ const effective = projectCapabilityEffective(project, cap, {+ agentMessagingDefault: settings.agentMessagingDefault+ })let display: string- if (granted) display = 'on (this project)'- else if (projectCapabilityFlagInFile(project, cap)) {+ if (effective.pendingNotice) {display =capabilityAnswerOf(project, cap) === 'declined'? 'off (the project file turns it on, but the user declined it on this machine)': 'off (the project file turns it on, but the user has not confirmed it on this machine yet)'- } else display = 'off (this project)'- return { key, scope: 'project', value: granted, display }+ } else {+ const why = effective.source === 'default' ? "this machine's default" : 'this project'+ display = `${effective.on ? 'on' : 'off'} (${why})`+ }+ return { key, scope: 'project', value: effective.on, display }}/** The text/plain + structured reply for `settings` / `settings --get <key>`. */export function renderSettingsGet(input: {keys: readonly SettingsVerbKey[]- settings: Pick<Settings, MachineKey>+ settings: SettingsVerbSettingsproject: SettingsProjectView | undefined}): { ok: true; message: string; result: unknown } | { ok: false; error: string } {const values: SettingsValue[] = []@@ -380,7 +387,7 @@ function showValue(key: SettingsVerbKey, v: boolean | number): string {*/export function planSettingsSet(input: {request: Extract<SettingsRequest, { action: 'set' }>- settings: Pick<Settings, MachineKey>+ settings: SettingsVerbSettingsproject: SettingsProjectView | undefinedrequestedBy: string}): SettingsSetPlan {@@ -393,7 +400,9 @@ export function planSettingsSet(input: {if (current.value === request.value) {return {kind: 'unchanged',- message: `${request.key} is already ${to}${spec.scope === 'project' && project ? ` in project "${project.name}"` : ''} — nothing changed`+ message:+ `${request.key} is already ${current.display}` ++ `${spec.scope === 'project' && project ? ` in project "${project.name}"` : ''} — nothing changed`}}const where =diff --git a/src/shared/types.ts b/src/shared/types.tsindex 9f4f84ef7..b2ef2aeaf 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -1684,6 +1684,15 @@ export interface Settings {* Scheduled/loop agents and sessions with live subagents are never touched* (renderer/terminal/hibernation-policy.ts explains why). */agentHibernationEnabled: boolean+ /**+ * Agent messaging for a project whose `.nodeterm/project.json` carries NO `agentMessaging` value+ * (@shared/project-capabilities, CAPABILITY_MACHINE_DEFAULTS). MACHINE-LOCAL on purpose: it is+ * this machine's user deciding for their own unconfigured projects, which is why it may answer+ * without a clone notice — while an explicit `true` in a cloned file still needs one, and an+ * explicit `false` still wins. Read strictly (`=== true`). Never settable from the canvas CLI+ * (@shared/settings-verb forbids it): it is a grant over every project at once.+ */+ agentMessagingDefault: boolean/** How long a session must be idle + offscreen before "Eco" hibernates it (minutes). */agentHibernationIdleMinutes: number/** When Eco hibernates a session, also mark it PAUSED (see `AgentNodeStatus.paused`) so it does@@ -1900,6 +1909,10 @@ export const DEFAULT_SETTINGS: Settings = {// Opt-in: hibernation exits a live CLI, so nobody gets it without asking. The 30-minute floor// is deliberately long — shorter windows exit sessions the user is between turns on.agentHibernationEnabled: false,+ // OFF until the cross-restart pane-ownership proof lands: messaging refuses every pane that+ // survived an app restart (core/agents/pane-ownership.ts), so "on by default" would be false+ // after every restart and every update. Flipping this is a separate, deliberate change.+ agentMessagingDefault: false,agentHibernationIdleMinutes: 30,agentHibernationPersistAcrossRestart: false,// Opt-out (default on). Existing users pick this up on hydrate ONLY if their settings.json has