{"record":{"id":"7392e6a386898029","repo":"can1357/oh-my-pi","slug":"unknown-subagent-or-session-file-unavailable-se","errorCode":null,"errorMessage":"Unknown subagent or session file unavailable: ${selector.subagentId}","messagePattern":"Unknown subagent or session file unavailable: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/modes/rpc/rpc-subagents.ts","lineNumber":253,"sourceCode":"\t\t\tprogress,\n\t\t});\n\t\tif (this.#subscriptionLevel !== \"off\") {\n\t\t\tthis.#output({ type: \"subagent_progress\", payload });\n\t\t}\n\t}\n\n\thandleEvent(payload: SubagentEventPayload): void {\n\t\tif (this.#staleSubagentIds.has(payload.id)) return;\n\t\tif (this.#subscriptionLevel !== \"events\") return;\n\t\tthis.#output({ type: \"subagent_event\", payload } satisfies RpcSubagentEventFrame);\n\t}\n\n\tresolveSessionFile(selector: RpcSubagentTranscriptSelector): string {\n\t\tif (selector.subagentId) {\n\t\t\tconst snapshot = this.#subagents.get(selector.subagentId);\n\t\t\tconst sessionFile = snapshot?.sessionFile ?? this.#transcriptSessionFilesBySubagentId.get(selector.subagentId);\n\t\t\tif (!sessionFile) {\n\t\t\t\tthrow new Error(`Unknown subagent or session file unavailable: ${selector.subagentId}`);\n\t\t\t}\n\t\t\treturn sessionFile;\n\t\t}\n\n\t\tif (selector.sessionFile) {\n\t\t\tif (this.#hasTranscriptSessionFile(selector.sessionFile)) return selector.sessionFile;\n\t\t\tthrow new Error(\"Unknown subagent session file\");\n\t\t}\n\n\t\tthrow new Error(\"get_subagent_messages requires subagentId or sessionFile\");\n\t}\n}\n","sourceCodeStart":235,"sourceCodeEnd":266,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/modes/rpc/rpc-subagents.ts#L235-L266","documentation":"resolveSessionFile maps a get_subagent_messages selector to a session file on disk. When a subagentId is given, it is looked up first in the live subagent snapshots, then in the transcript's subagent-id-to-session-file index; if neither has the id (or the recorded file is absent), the resolver throws 'Unknown subagent or session file unavailable'.","triggerScenarios":"Requesting subagent messages with a subagentId that was never spawned in this session, that has already been evicted from the registry and has no transcript mapping, or that belongs to a different session.","commonSituations":"A host caches subagent IDs from a previous run and queries them after a restart; a typo'd or stale ID from an external tool; querying before the subagent has registered its session file.","solutions":["Use the subagentId exactly as returned when the subagent was spawned; list current subagents to confirm the ID.","If the session was restarted, resolve via the sessionFile path directly instead of the old subagentId.","Retry only after confirming the subagent has started and registered; otherwise treat as a permanent unknown-ID error."],"exampleFix":"// before\nconst file = subagents.resolveSessionFile({ subagentId: oldId }); // oldId from previous run\n// after\nconst file = subagents.resolveSessionFile({ sessionFile: knownSessionPath });","handlingStrategy":"try-catch","validationCode":"// confirm the id exists in the current session's subagent list before querying\nconst known = await rpc.listSubagents();\nif (!known.some(s => s.id === selector.subagentId)) throw new Error(`subagent ${selector.subagentId} not in this session`);","typeGuard":null,"tryCatchPattern":"try {\n  const file = subagents.resolveSessionFile({ subagentId });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"Unknown subagent or session file unavailable\")) {\n    // fall back to sessionFile-based lookup or report unknown id\n  } else throw err;\n}","preventionTips":["Only use subagentIds returned by the spawn/list APIs of the same live session.","Clear cached subagent IDs on session restart.","Prefer sessionFile selectors when working with historical transcripts."],"tags":["rpc","subagents","lookup","state"],"backgroundTag":"unknown-subagent-id","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}