Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(cli): bind Muse 1.4 panes: its session folders and permission frame (#1359)

0xdiego25f9f8a9f2ebfd
diff --git a/cli/src/engines/kit/sessionIdentity.spec.ts b/cli/src/engines/kit/sessionIdentity.spec.ts
index add266cf0..f4ca93f61 100644
--- a/cli/src/engines/kit/sessionIdentity.spec.ts
+++ b/cli/src/engines/kit/sessionIdentity.spec.ts
@@ -40,6 +40,14 @@ it('a file from another workspace cannot hold this workspace on a late marker',
it.each(['', 'bad\n', 'null\n', '[]\n', '{"header":[]}\n', header + '{"run":'])('holds an incomplete or invalid identity: %j', async text => {
await expect(readRunIdentity(rule, pathFor(text), async () => true)).rejects.toThrow('identity is held')
})
+it('skips declared preamble records before the workspace header, and only those', async () => {
+ const framed: RunIdentity = { ...rule, bytes: [64, 512], preamble: ['frame'] }
+ const frame = JSON.stringify({ frame: 'permission', children: [] }) + '\n'
+ await expect(readRunIdentity(framed, pathFor(frame + frame + header + run), async () => true)).resolves.toEqual({ cwd: '/work' })
+ await expect(readRunIdentity(rule, pathFor(frame + header + run), async () => true)).rejects.toThrow('identity is held')
+ await expect(readRunIdentity(framed, pathFor(frame + 'bad\n' + header + run), async () => true)).rejects.toThrow('identity is held')
+ await expect(readRunIdentity(framed, pathFor(frame), async () => true)).rejects.toThrow('identity is held')
+})
it('excludes a complete background task with a valid workspace header', async () => {
await expect(readRunIdentity(rule, pathFor(header + '{"run":{"kind":"task"}}'), async () => true)).resolves.toBeNull()
})
diff --git a/cli/src/engines/kit/sessionIdentity.ts b/cli/src/engines/kit/sessionIdentity.ts
index c791edd9b..3f4f0fd8d 100644
--- a/cli/src/engines/kit/sessionIdentity.ts
+++ b/cli/src/engines/kit/sessionIdentity.ts
@@ -17,6 +17,9 @@ export interface RunIdentity {
bytes: readonly number[]
cwd: Field
run: readonly { field: Field; value: string }[]
+ /** A field that marks a record the engine writes ahead of the workspace header (Muse 1.4's retained permission
+ * frame): such records are skipped, and the header is the first record without it. */
+ preamble?: Field
}
export interface NativeSessionHead { sessionId: string; cwd: string }
@@ -67,7 +70,18 @@ export async function readRunIdentity(rule: RunIdentity, path: string, matches:
const lines = head.subarray(0, bytes).toString('utf8').split('\n')
if (!complete) lines.pop()
if (!lines.length) continue
- const cwd = valueAt(parsed(lines[0]!), rule.cwd)
+ let first = 0
+ while (rule.preamble && first < lines.length) {
+ const record = parsed(lines[first]!)
+ if (record === null || valueAt(record, rule.preamble) === undefined) break
+ first++
+ }
+ if (first === lines.length) {
+ // Only preamble so far: the header lies beyond this head, or nowhere.
+ if (complete) throw new IdentityReadUnavailable('the workspace header is incomplete or invalid')
+ continue
+ }
+ const cwd = valueAt(parsed(lines[first]!), rule.cwd)
if (typeof cwd !== 'string' || !isAbsolute(cwd)) throw new IdentityReadUnavailable('the workspace header is incomplete or invalid')
if (!await matches(cwd)) return null
let malformed = false
diff --git a/cli/src/engines/muse/contract.ts b/cli/src/engines/muse/contract.ts
index 04845ffd8..215c346b5 100644
--- a/cli/src/engines/muse/contract.ts
+++ b/cli/src/engines/muse/contract.ts
@@ -5,4 +5,6 @@ export const MUSE_IDENTITY: RunIdentity = {
bytes: [64 * 1024, 4 * 1024 * 1024],
cwd: ['payload', 'record', 'workspace_root'],
run: [{ field: ['payload', 'kind'], value: 'run' }, { field: ['payload', 'event', 'kind'], value: 'started' }],
+ // Muse Code 1.4 opens a transcript with a retained permission transaction; the workspace record follows it.
+ preamble: ['retained_frame'],
}
diff --git a/cli/src/lib/sessionRepair.bounds.spec.ts b/cli/src/lib/sessionRepair.bounds.spec.ts
index a602b86f3..b2f405175 100644
--- a/cli/src/lib/sessionRepair.bounds.spec.ts
+++ b/cli/src/lib/sessionRepair.bounds.spec.ts
@@ -105,9 +105,9 @@ describe('complete bounded evidence before choosing a conversation', () => {
await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
})
- it('binds a Muse session whose folder also holds its tool outputs', async () => {
- // Muse Code 1.4 writes `tool-outputs/` beside `session.jsonl`, one level below the 4 the tree allows:
- // walked into, it held every Muse pane on "the transcript depth limit was reached".
+ it('binds a Muse session whatever folders it keeps beside its transcript', async () => {
+ // Muse Code 1.4 keeps folders of its own beside `session.jsonl` (`tool-outputs/`, `approval-review/`, …), one
+ // level below the 4 the tree allows: walked into, each held every Muse pane on "the transcript depth limit was reached".
const work = join(root, 'work')
mkdirSync(work)
const folder = join(root, 'muse', 'sessions', '2026', '10', '09', SID)
@@ -116,10 +116,24 @@ describe('complete bounded evidence before choosing a conversation', () => {
JSON.stringify({ payload: { kind: 'run', event: { kind: 'started', prompt: 'hi' } } }),
].join('\n') + '\n', START + 5_000)
file(join(folder, 'tool-outputs', 'call_1.txt'), 'output')
+ file(join(folder, 'approval-review', 'note.txt'), 'x')
+ file(join(folder, 'a-folder-muse-adds-next', 'deeper', 'x.jsonl'), body())
file(join(folder, 'subagent', 'child', 'session.jsonl'), 'x')
await expect(repair.findLiveSession('muse', work, START)).resolves.toEqual({ sessionId: SID, transcriptPath: path })
})
+ it('binds a Muse 1.4 session whose transcript opens with a retained permission frame', async () => {
+ const work = join(root, 'work')
+ mkdirSync(work)
+ const folder = join(root, 'muse', 'sessions', '2026', '10', '09', SID)
+ const path = file(join(folder, 'session.jsonl'), [
+ JSON.stringify({ retained_frame: 'session_permission_transaction', frame_schema_version: 1, children: [] }),
+ JSON.stringify({ payload: { kind: 'session', record: { workspace_root: work } } }),
+ JSON.stringify({ payload: { kind: 'run', event: { kind: 'started', prompt: 'hi' } } }),
+ ].join('\n') + '\n', START + 5_000)
+ await expect(repair.findLiveSession('muse', work, START)).resolves.toEqual({ sessionId: SID, transcriptPath: path })
+ })
+
it('holds on an unreadable subtree and recovers on a later complete scan', async () => {
const path = transcript()
const hidden = join(root, 'claude', 'projects', 'unknown'); mkdirSync(hidden)
diff --git a/cli/src/lib/sessionRepair.ts b/cli/src/lib/sessionRepair.ts
index c1b27fd94..2427d729f 100644
--- a/cli/src/lib/sessionRepair.ts
+++ b/cli/src/lib/sessionRepair.ts
@@ -70,20 +70,21 @@ export interface RepairedSession {
hermesHome?: string
}
-/** The folders beside a Muse `session.jsonl` that are not conversations: skipped, not walked into (and so
- * never counted against MAX_DEPTH). */
-const MUSE_NON_TRANSCRIPT_FOLDERS = ['subagent', 'tool-outputs'] as const
+/** How deep Muse's session folders sit (`sessions/YYYY/MM/DD/<uuid>/`): every folder inside one is Muse's own
+ * (`subagent/`, `tool-outputs/`, `approval-review/`, and whatever a later version adds), never a conversation
+ * of the pane, so it is skipped rather than walked into and counted against MAX_DEPTH. */
+const MUSE_SESSION_FOLDER_DEPTH = 4
interface TranscriptFile { path: string; mtimeMs: number; birthMs: number }
/** Collect a complete bounded pool. Truncation must never make two conversations look like one. */
-async function transcripts(root: string, budget: { remaining: number }, out: TranscriptFile[], excluded: readonly string[] = [], depth = 0): Promise<void> {
+async function transcripts(root: string, budget: { remaining: number }, out: TranscriptFile[], excluded: readonly string[] = [], depth = 0, leafDepth?: number): Promise<void> {
for await (const entry of identityEntries(root, budget, depth === 0)) {
const full = join(root, entry.name)
if (entry.isDirectory()) {
- if (excluded.includes(entry.name)) continue
+ if (excluded.includes(entry.name) || (leafDepth !== undefined && depth >= leafDepth)) continue
if (depth >= MAX_DEPTH) throw new IdentityReadUnavailable('the transcript depth limit was reached')
- await transcripts(full, budget, out, excluded, depth + 1)
+ await transcripts(full, budget, out, excluded, depth + 1, leafDepth)
continue
}
if (!entry.name.endsWith('.jsonl') || entry.name.includes('.checkpoints.')) continue
@@ -226,7 +227,7 @@ async function fileEngineSession(
cwd: string,
startedAtMs: number,
readMeta: (path: string) => Promise<TranscriptMeta | null>,
- opts?: { bornOnly?: boolean; excludedDirectories?: readonly string[]; excludedSessionId?: string },
+ opts?: { bornOnly?: boolean; excludedDirectories?: readonly string[]; leafDepth?: number; excludedSessionId?: string },
): Promise<RepairedSession | null> {
const since = startedAtMs - START_SLACK_MS
const born: RepairedSession[] = []
@@ -235,7 +236,7 @@ async function fileEngineSession(
const files: TranscriptFile[] = []
const budget = identityScanBudget()
for (const directory of typeof root === 'string' ? [root] : root) {
- await transcripts(directory, budget, files, opts?.excludedDirectories)
+ await transcripts(directory, budget, files, opts?.excludedDirectories, 0, opts?.leafDepth)
}
files.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
for (const file of files) {
@@ -383,8 +384,9 @@ export async function findLiveSession(
// Muse's hooks never fire, so this scan is the ONLY way a muse pane is ever bound. The tree is
// `sessions/YYYY/MM/DD/<session-uuid>/session.jsonl` (4 levels — exactly MAX_DEPTH) and nothing in
// the path names the project: `workspace_root` in the first record is the only link. Sub-agent
- // files live one level deeper under `subagent/`, and must never be adopted as agents of their own;
- // `tool-outputs/` (Muse Code 1.4) sits there too and holds no conversation.
+ // files live one level deeper under `subagent/`, and must never be adopted as agents of their own; Muse
+ // keeps more folders of its own there (`tool-outputs/`, `approval-review/`), so nothing below a session
+ // folder is walked (MUSE_SESSION_FOLDER_DEPTH).
return fileEngineSession(join(env.MUSE_HOME, 'sessions'), cwd, startedAtMs, async (path) => {
if (path.includes(`${sep}subagent${sep}`)) return null
// Muse opens sessions of its OWN under the same workspace_root — memory reminders
@@ -395,7 +397,7 @@ export async function findLiveSession(
// being conversed in has opened a RUN.
const identity = await museSessionIdentity(path, root => sameDir(root, cwd))
return identity ? { ...identity, sessionId: basename(dirname(path)) } : null
- }, { ...opts, excludedDirectories: MUSE_NON_TRANSCRIPT_FOLDERS })
+ }, { ...opts, leafDepth: MUSE_SESSION_FOLDER_DEPTH })
}
case 'amp':
// The transcripts scanned here are the adapter's own — Amp keeps no conversation on disk, so its