Skip to content

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.

feat(messaging): machine-local agentMessaging default (ships off)

enes4c12a285b084
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 grant
capabilities, 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`) and
bridged to it, wrapped in a `Verify: <title>` group, plus a judge armed behind the whole panel.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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. Anything
machine-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: the
request names the agent's own node, and the dispatch has to find the canvas that owns it. For
diff --git a/src/core/agents/agent-messaging.ts b/src/core/agents/agent-messaging.ts
index 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.ts
index 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 const
it('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 true
expect(
projectCapabilityGrantedFor(
{ ...baseProject, agentBrowserControl: true, capabilityAck: { [cap]: 'declined' } },
- cap
- )
+ cap, {})
).toBe(false)
// non-literal-true file value never grants, answer or no answer
expect(
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.ts
index 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.ts
index 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) continue
diff --git a/src/main/agent-messaging-switch.test.ts b/src/main/agent-messaging-switch.test.ts
index 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, minus
const 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, minus
expect(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 stor
const 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.El
const 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}>
<FieldRow
label="Hibernate idle agents"
diff --git a/src/renderer/lib/capabilityChoice.ts b/src/renderer/lib/capabilityChoice.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 p
if (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.ts
index 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.ts
index 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 }) | undefined
projectName(projectId: string): string | undefined
settings(): Settings
}
diff --git a/src/shared/project-capabilities.ts b/src/shared/project-capabilities.ts
index 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 out
for (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.ts
index 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 inherit
diff --git a/src/shared/settings-verb.test.ts b/src/shared/settings-verb.test.ts
index 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.ts
index 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: SettingsVerbSettings
project: 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: SettingsVerbSettings
project: SettingsProjectView | undefined
requestedBy: 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.ts
index 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