Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import fs from 'node:fs'
import path from 'node:path'
import process from 'node:process'
import { pathToFileURL } from 'node:url'
import ts from 'typescript-api'
import {
diffCounts,
formatCountBaseline,
listTrackedFiles,
parseCountBaseline,
pruneCountBaseline,
totalCount
} from './ratchet-baseline.mjs'
// Ratchet layout writers downward: main Store/session-partition writes and renderer layout/selection keys/spreads.
// Exclude existing-entry content updates; shorthand counts only in store writes, and deleted symbols stay compiler-owned.
// Partition fields of the saved workspace session (census class 1).
const SESSION_PARTITION_FIELDS = [
'tabsByWorktree',
'terminalLayoutsByTabId',
'unifiedTabs',
'tabGroups',
'tabGroupLayouts',
'activeGroupIdByWorktree',
'activeTabIdByWorktree',
'activeWorktreeId',
'openFilesByWorktree',
'browserTabsByWorktree',
'activeBrowserTabIdByWorktree',
'activeFileIdByWorktree',
'activeTabTypeByWorktree',
'tabBarOrderByWorktree',
'sleepingAgentSessionsByPaneKey',
'terminalPtyIncarnationsByPaneKey',
'defaultTerminalTabsAppliedByWorktreeId',
'lastVisitedAtByWorktreeId',
'browserUrlHistory'
]
const SESSION_FIELDS = ['workspaceSession', 'workspaceSessionsByHostId']
// Tab and pane-layout fields edited in place inside a partition (census class 1, third search).
const SESSION_TAB_FIELDS = [
'ptyId',
'ptyIdsByLeafId',
'customTitle',
'titlesByLeafId',
'buffersByLeafId',
'activeLeafId'
]
// Window layout fields of acceptance 1 and the per-view selection fields (census class 2).
const RENDERER_LAYOUT_FIELDS = new Set([
'tabsByWorktree',
'terminalLayoutsByTabId',
'tabBarOrderByWorktree',
'unifiedTabsByWorktree',
'groupsByWorktree',
'layoutByWorktree',
'openFiles',
'browserTabsByWorktree',
'activeGroupIdByWorktree',
'activeTabIdByWorktree',
'activeTabId',
'activeFileIdByWorktree',
'activeFileId',
'activeBrowserTabIdByWorktree',
'activeBrowserTabId',
'activeTabTypeByWorktree',
'activeTabType',
'ptyIdsByTabId'
])
export const RATCHETS = [
{
id: 'main',
label: 'main-process layout writer(s)',
scanRoot: 'src/main',
baselinePath: 'config/main-layout-writer-baseline.txt',
// Count Store layout setter calls and method values, including internal partition writers.
writerNames: new Set([
'setWorkspaceSession',
'patchWorkspaceSession',
'stageWorkspaceSessionBeforeUnload',
'setWorkspaceSessionForWorktree',
'setForWorktree',
'persistPtyBinding',
'retirePtyBinding',
'moveTerminalLeafToNewTab',
'admitTerminalPane',
'withdrawTerminalPane',
'removeWorkspaceSessionHost',
'removeWorkspaceSessionStateForWorktree',
'setHostWorkspaceSession',
'setLocalWorkspaceSession',
'applyPtyBinding',
'removeWorkspaceSessionOwner',
'removeWorkspaceSessionOwners',
'removeWorkspaceSessionOwnerEverywhere',
'removeWorkspaceSessionOwnersEverywhere',
'removeWorkspaceSessionOwnerInPartition',
'deleteScannedSessionFieldsForOwners',
'removeRepoFromWorkspaceSession',
'removeRepoFromHostWorkspaceSessions',
'applyPreparedOrcadMigrationWorkspaceSession',
'applyPayloadToTarget',
'removeSourceRepo',
'clearSshRemotePtyBindingsForTarget',
'clearSshRemotePtyBindingsForLeases'
]),
assignedFields: new Set([
...SESSION_FIELDS,
...SESSION_PARTITION_FIELDS,
...SESSION_TAB_FIELDS,
'mobileClientTabSelectionsByDeviceId'
]),
// These names also key unrelated main objects, so only the session itself counts as a key.
keyedFields: new Set(SESSION_FIELDS),
entryContentFields: new Set(),
allowed: () => false,
header: [
'# Main-process writers of saved workspace layout, per file: calls of the Store layout',
'# setters, plus assignments, deletes and object keys that edit session partitions directly.',
'# This is a RATCHET: counts may only go DOWN. Layout moves to one runtime owner; do not add',
'# writers. Prune after removing writers: pnpm check:layout-writer-ratchets --prune'
]
},
{
id: 'renderer',
label: 'renderer layout write(s)',
scanRoot: 'src/renderer/src',
baselinePath: 'config/renderer-layout-writer-baseline.txt',
writerNames: new Set(),
assignedFields: RENDERER_LAYOUT_FIELDS,
keyedFields: RENDERER_LAYOUT_FIELDS,
// Mapping existing entries preserves membership/order; treat draft/status/URL edits as content only.
entryContentFields: new Set(['openFiles', 'browserTabsByWorktree']),
// The three writers the plan allows: applyFromRuntime, the frozen mirror's store patch and
// the frozen setters for remote-server workspaces.
allowed: (rel) =>
rel === 'src/renderer/src/store/workspace-layout-cache.ts' ||
rel === 'src/renderer/src/runtime/web-session-tabs-sync/store-patch.ts' ||
rel.startsWith('src/renderer/src/runtime/remote-workspace-frozen/'),
header: [
'# Renderer writes of the window layout and per-view selection fields, per file: assignments,',
'# deletes, object keys and string keys (computed-key writes). Same-name copies are reads.',
'# This is a RATCHET: counts may only GO DOWN. Layout comes from the runtime; send a command',
'# instead. Prune after removing writes: pnpm check:layout-writer-ratchets --prune'
]
}
]
// Census test filter: test, fixture and harness files are not product writers.
export function isScannedPath(rel) {
return (
/\.(ts|tsx)$/.test(rel) &&
!/\.(test|spec)\.|\/tests?\/|__tests__|test-support|fixture|harness|e2e\//.test(rel)
)
}
const ASSIGNMENT_OPERATORS = new Set([
ts.SyntaxKind.EqualsToken,
ts.SyntaxKind.QuestionQuestionEqualsToken,
ts.SyntaxKind.BarBarEqualsToken,
ts.SyntaxKind.AmpersandAmpersandEqualsToken
])
/** A string-literal key; a variable key (`exitCodes[ptyId]`) names no field. */
function literalKey(node) {
return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : null
}
function staticName(node) {
if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node)) {
return node.text
}
if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
return node.text
}
if (ts.isComputedPropertyName(node)) {
return literalKey(node.expression)
}
return null
}
/** The field a write target (`a.b[c]!.d`) goes through, if any; root identifiers are locals. */
function targetedField(node, fields) {
let current = node
while (current) {
if (
ts.isParenthesizedExpression(current) ||
ts.isNonNullExpression(current) ||
ts.isAsExpression(current) ||
ts.isSatisfiesExpression(current)
) {
current = current.expression
} else if (ts.isPropertyAccessExpression(current)) {
if (fields.has(current.name.text)) {
return current.name.text
}
current = current.expression
} else if (ts.isElementAccessExpression(current)) {
const key = literalKey(current.argumentExpression)
if (key !== null && fields.has(key)) {
return key
}
current = current.expression
} else {
return null
}
}
return null
}
function unwrap(node) {
let current = node
while (
ts.isParenthesizedExpression(current) ||
ts.isNonNullExpression(current) ||
ts.isAsExpression(current) ||
ts.isSatisfiesExpression(current)
) {
current = current.expression
}
return current
}
/** An existing value read as-is: `s.openFiles`, `s.tabs[id] ?? []`. */
function isPlainRead(node) {
const current = unwrap(node)
if (ts.isIdentifier(current) || current.kind === ts.SyntaxKind.ThisKeyword) {
return true
}
if (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
return isPlainRead(current.expression)
}
if (
ts.isBinaryExpression(current) &&
(current.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
current.operatorToken.kind === ts.SyntaxKind.BarBarToken)
) {
const right = unwrap(current.right)
const emptyLiteral =
(ts.isArrayLiteralExpression(right) && right.elements.length === 0) ||
(ts.isObjectLiteralExpression(right) && right.properties.length === 0)
return isPlainRead(current.left) && (emptyLiteral || isPlainRead(right))
}
return false
}
/** `list.map(…)`, or `{ ...map, [key]: list.map(…) }`: same entries in the same order. */
function keepsMembership(node) {
const value = unwrap(node)
if (ts.isCallExpression(value)) {
const callee = unwrap(value.expression)
return (
ts.isPropertyAccessExpression(callee) &&
callee.name.text === 'map' &&
isPlainRead(callee.expression)
)
}
if (ts.isObjectLiteralExpression(value)) {
return value.properties.every(
(property) =>
(ts.isSpreadAssignment(property) && isPlainRead(property.expression)) ||
(ts.isPropertyAssignment(property) && keepsMembership(property.initializer))
)
}
return false
}
const STORE_SET_CALLS = new Set(['set', 'setState'])
/** Whether an object literal is a store write: `set({ … })`, `set((s) => ({ … }))` or a writer call. */
function isPassedToWriter(objectLiteral, writerNames) {
let node = objectLiteral
for (;;) {
const parent = node.parent
if (
ts.isParenthesizedExpression(parent) ||
ts.isAsExpression(parent) ||
ts.isSatisfiesExpression(parent) ||
ts.isConditionalExpression(parent)
) {
node = parent
} else if (ts.isArrowFunction(parent) && parent.body === node) {
node = parent
} else if (ts.isReturnStatement(parent)) {
let fn = parent.parent
while (fn && !ts.isFunctionLike(fn)) {
fn = fn.parent
}
if (!fn) {
return false
}
node = fn
} else {
break
}
}
const call = node.parent
if (!ts.isCallExpression(call) || !call.arguments.includes(node)) {
return false
}
const callee = unwrap(call.expression)
const name = ts.isIdentifier(callee)
? callee.text
: ts.isPropertyAccessExpression(callee)
? callee.name.text
: null
return name !== null && (STORE_SET_CALLS.has(name) || writerNames.has(name))
}
/** `{ tabsByWorktree: s.tabsByWorktree }` copies a value under its own name: a selector read. */
function isSameNameCopy(property, name) {
let value = property.initializer
while (ts.isParenthesizedExpression(value) || ts.isNonNullExpression(value)) {
value = value.expression
}
return ts.isPropertyAccessExpression(value) && value.name.text === name
}
/** Layout writes in one file under one ratchet's rules. */
export function countLayoutWrites(sourceText, ratchet, fileName = 'file.tsx') {
const names = [...ratchet.writerNames, ...ratchet.assignedFields]
if (!names.some((name) => sourceText.includes(name))) {
return 0
}
const sourceFile = ts.createSourceFile(
fileName,
sourceText,
ts.ScriptTarget.Latest,
true,
fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS
)
let count = 0
const visit = (node) => {
if (
(ts.isPropertyAccessExpression(node) && ratchet.writerNames.has(node.name.text)) ||
(ts.isCallExpression(node) &&
ts.isIdentifier(node.expression) &&
ratchet.writerNames.has(node.expression.text))
) {
count += 1
} else if (
ts.isBinaryExpression(node) &&
ASSIGNMENT_OPERATORS.has(node.operatorToken.kind) &&
targetedField(node.left, ratchet.assignedFields) !== null
) {
const field = targetedField(node.left, ratchet.assignedFields)
if (!(ratchet.entryContentFields.has(field) && keepsMembership(node.right))) {
count += 1
}
} else if (
ts.isDeleteExpression(node) &&
targetedField(node.expression, ratchet.assignedFields) !== null
) {
count += 1
} else if (
ts.isShorthandPropertyAssignment(node) &&
ratchet.keyedFields.has(node.name.text) &&
// A shorthand elsewhere passes a value on (`return { activeTabId, tabsByWorktree }`).
isPassedToWriter(node.parent, ratchet.writerNames)
) {
count += 1
} else if (ts.isPropertyAssignment(node)) {
const name = staticName(node.name)
if (
name !== null &&
ratchet.keyedFields.has(name) &&
!isSameNameCopy(node, name) &&
!(ratchet.entryContentFields.has(name) && keepsMembership(node.initializer))
) {
count += 1
}
} else if (
(ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) &&
ratchet.keyedFields.has(node.text) &&
// Object keys and element reads are judged above; `'tabsByWorktree'` elsewhere feeds a
// computed-key write (`patch[key] = …`), which cannot be resolved statically.
!(ts.isPropertyAssignment(node.parent) && node.parent.name === node) &&
!ts.isComputedPropertyName(node.parent) &&
!(ts.isElementAccessExpression(node.parent) && node.parent.argumentExpression === node) &&
!(
ts.isCallExpression(node.parent) &&
!node.parent.questionDotToken &&
node.parent.arguments.length === 2 &&
node.parent.arguments[1] === node &&
ts.isPropertyAccessExpression(node.parent.expression) &&
!node.parent.expression.questionDotToken &&
ts.isIdentifier(node.parent.expression.expression) &&
node.parent.expression.expression.text === 'Object' &&
node.parent.expression.name.text === 'hasOwn'
) &&
!ts.isLiteralTypeNode(node.parent)
) {
count += 1
}
ts.forEachChild(node, visit)
}
visit(sourceFile)
return count
}
export function collectCurrentCounts(ratchet, root = process.cwd()) {
const counts = new Map()
for (const rel of listTrackedFiles(root, [ratchet.scanRoot]).filter(isScannedPath)) {
if (ratchet.allowed(rel)) {
continue
}
let text
try {
text = fs.readFileSync(path.join(root, rel), 'utf8')
} catch {
// Deleted in the working tree but still tracked.
continue
}
const found = countLayoutWrites(text, ratchet, rel)
if (found > 0) {
counts.set(rel, found)
}
}
return counts
}
const ADVICE =
'Workspace layout is moving to one runtime owner; send a layout command instead of writing it here.'
export function main(root = process.cwd()) {
let failed = false
for (const ratchet of RATCHETS) {
const baselineFile = path.join(root, ratchet.baselinePath)
if (!fs.existsSync(baselineFile)) {
console.error(`::error::Missing ${ratchet.baselinePath}.`)
failed = true
continue
}
const current = collectCurrentCounts(ratchet, root)
const { grown, shrunk } = diffCounts(
current,
parseCountBaseline(fs.readFileSync(baselineFile, 'utf8'))
)
for (const { file, now, allowed } of grown) {
console.error(
`::error file=${file}::${now} ${ratchet.label}, baseline allows ${allowed}. ${ADVICE}`
)
}
// Why: a removal must not fail PRs that branched before it; only growth fails.
for (const { file, now, allowed } of shrunk) {
console.warn(
`::warning file=${file}::${now} ${ratchet.label}, baseline still allows ${allowed}. Run: pnpm check:layout-writer-ratchets --prune`
)
}
if (grown.length > 0) {
failed = true
} else {
console.log(
`Layout-writer ratchet (${ratchet.id}) OK — ${totalCount(current)} ${ratchet.label}.`
)
}
}
return failed ? 1 : 0
}
export function prune(root = process.cwd()) {
for (const ratchet of RATCHETS) {
const current = collectCurrentCounts(ratchet, root)
const kept = pruneCountBaseline(root, ratchet.baselinePath, ratchet.header, current)
console.log(`Pruned ${ratchet.baselinePath} to ${kept} ${ratchet.label}.`)
}
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
const root = process.cwd()
if (process.argv[2] === '--init') {
// One-time bootstrap of the baselines from today's tree.
for (const ratchet of RATCHETS) {
const counts = collectCurrentCounts(ratchet, root)
fs.writeFileSync(
path.join(root, ratchet.baselinePath),
formatCountBaseline(counts, ratchet.header)
)
}
} else if (process.argv[2] === '--prune') {
prune(root)
}
process.exit(main(root))
}