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
/**
* The one-time clone notice, decided ONCE for every capability — pure, shared, and the only
* decider either feature may use (browser control here in PR 3; agent messaging adopts it in its
* PR 6 without reimplementing anything).
*
* A switch that arrives from a clone is not the same thing as a switch the user set:
* `.nodeterm/project.json` is git-shared and hand-editable, so `agentBrowserControl: true` in a
* freshly cloned repo is a stranger's decision until this machine's user has seen it. The
* acknowledgment is therefore recorded MACHINE-LOCALLY (`IndexEntryV3.capabilityAck` — the index
* entry is the only authority for project identity), never in the shared file; a second worktree
* of the same repo is a second entry, hence a second notice, on purpose.
*
* THE ACK CARRIES THE ANSWER, not just the fact of one (PR #213 review, C1). "Turn it off" can
* only delete the field from THIS working copy — the hostile `true` survives in git and a routine
* `git checkout`/pull restores it. If the ack were a bare bit, that restored `true` would meet a
* standing acknowledgment and grant silently to a user who explicitly said no. So:
* - `'kept'` — explicit consent; enabled+kept is the ONE granting combination.
* - `'declined'` — explicit refusal; if the file's `true` ever re-arrives it is refused AND a
* NEW notice is raised (never silence, never a grant without a fresh "keep").
* - absent — never answered (or dismissed without answering — dismissal is not an answer);
* enabled+absent is a pending notice and a refusal.
* Each rule is pinned by `project-capability-consent.test.ts`.
*
* Lives in `src/shared` for the same reason as `safe-id.ts`: the renderer raises the dialog and may
* not import `src/core`; `core/project-capability-consent.ts` re-exports these for main/core
* callers, and its test pins that the two paths are the same function objects.
*/
import {
capabilityHasMachineDefault,
capabilityMachineDefault,
projectCapabilityFileState,
type CapabilityMachineDefaults,
type ProjectCapability
} from './project-capabilities'
/** What this machine's user answered when told about a capability switch. */
export type CapabilityAnswer = 'kept' | 'declined'
/** The machine-local answer record, keyed like the capability fields but never written to the
* shared project file (`projectToFile` does not know this shape exists — pinned by the consent
* test with an ack-carrying project as input). */
export type CapabilityAckMap = Partial<Record<ProjectCapability, CapabilityAnswer>>
export interface CapabilityConsentState {
capability: ProjectCapability
/** The strict read of the shared file's switch (`projectCapabilityFlagInFile` — literal true
* only). NEVER a grant by itself. */
enabledInFile: boolean
/** This machine's recorded answer for this project entry, if any. */
answer: CapabilityAnswer | undefined
}
/** On in the file + not explicitly KEPT on this machine ⇒ notice. That covers both the
* never-answered clone window and the re-arrival of a `true` the user declined (C1): a recorded
* "no" makes a re-appearing switch a NEW event to be told about, not a settled one. Off needs no
* warning, whatever was answered. */
export function needsCapabilityNotice(s: CapabilityConsentState): boolean {
return s.enabledInFile === true && s.answer !== 'kept'
}
/**
* May the capability act RIGHT NOW? Only `enabledInFile && answer === 'kept'`: a pending notice is
* a refusal, and a recorded DECLINE is a refusal even when the hostile `true` re-arrives via git
* (`project-capability-consent.test.ts` — "a switch that is on but unanswered grants nothing",
* "a DECLINED switch grants nothing even when the file says true again"). This is the predicate
* the browser ledger's admission check (PR 4) and messaging's `messagingEnabled` wiring (PR 6)
* consult per call — never cached at lease start.
*/
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 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,
defaults: CapabilityMachineDefaults
): boolean {
return projectCapabilityEffective(p, cap, defaults).on
}
/** This machine's recorded answer, own properties only (M-1: an in-process object must not inherit
* consent through its prototype; JSON never produces one, but callers are not only JSON). */
export function capabilityAnswerOf(
p: { capabilityAck?: CapabilityAckMap } | undefined | null,
cap: ProjectCapability
): CapabilityAnswer | undefined {
const ack = p?.capabilityAck
if (!ack || !Object.prototype.hasOwnProperty.call(ack, cap)) return undefined
const v = ack[cap]
return v === 'kept' || v === 'declined' ? v : undefined
}
/**
* Returns `entry` with the capability answered — a new object, input untouched; a later answer
* overwrites an earlier one (decline → later explicit keep must win, and vice versa). Works on any
* entry-shaped record (`IndexEntryV3` in main, the renderer's `Project` mirror of the same
* machine-local field) so both sides record the answer through the one function.
*/
export function recordCapabilityAck<E extends { capabilityAck?: CapabilityAckMap }>(
entry: E,
cap: ProjectCapability,
answer: CapabilityAnswer
): E {
return { ...entry, capabilityAck: { ...entry.capabilityAck, [cap]: answer } }
}