{"record":{"id":"18ecdad450e16bc0","repo":"Yeachan-Heo/oh-my-codex","slug":"launch-instructions-file-not-found-appendixpath","errorCode":null,"errorMessage":"launch instructions file not found: ${appendixPath}","messagePattern":"launch instructions file not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/index.ts","lineNumber":5520,"sourceCode":"            args: [\"set-option\", \"-t\", sessionName, OMX_INSTANCE_OPTION, sessionId],\n          },\n        ]\n      : []),\n    { name: \"split-and-capture-hud-pane\", args: splitCaptureArgs },\n  ];\n}\n\nasync function readLaunchAppendInstructions(): Promise<string> {\n  const appendixCandidates = [\n    process.env[OMX_RALPH_APPEND_INSTRUCTIONS_FILE_ENV]?.trim(),\n    process.env[OMX_AUTORESEARCH_APPEND_INSTRUCTIONS_FILE_ENV]?.trim(),\n  ].filter(\n    (value): value is string => typeof value === \"string\" && value.length > 0,\n  );\n  if (appendixCandidates.length === 0) return \"\";\n  const appendixPath = appendixCandidates[0];\n  if (!existsSync(appendixPath)) {\n    throw new Error(`launch instructions file not found: ${appendixPath}`);\n  }\n  const { readFile } = await import(\"fs/promises\");\n  return (await readFile(appendixPath, \"utf-8\")).trim();\n}\n\nexport function shouldAttachDetachedTmuxSession(\n  env: NodeJS.ProcessEnv = process.env,\n): boolean {\n  return env.OMX_HERMES_MCP_BRIDGE !== \"1\";\n}\n\nfunction stripHermesMcpBridgeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n  const { OMX_HERMES_MCP_BRIDGE: _bridge, ...rest } = env;\n  return rest;\n}\n\nexport function buildDetachedSessionFinalizeSteps(\n  sessionName: string,","sourceCodeStart":5502,"sourceCodeEnd":5538,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/index.ts#L5502-L5538","documentation":"A configured launch-instructions appendix file (an extra prompt/instructions file to append at launch) was specified but does not exist on disk. The builder refuses to silently skip it, so it throws with the offending path.","triggerScenarios":"Configuration (e.g. agent config or launch flags) points at an instructions appendix path that is missing — relative path resolved against an unexpected cwd, a typo, a file not committed/created, or a worktree where the file exists only on another branch.","commonSituations":"Teammates cloning a repo where a local uncommitted instructions file is configured; running OMX from a different directory so a relative path no longer resolves; renamed or deleted instruction files after a refactor.","solutions":["Check the path in the error message and create or restore the file","If the path is relative, run from the project root or change the config to an absolute/repo-relative path that resolves from the launch cwd","Remove the appendix setting from config if the file is no longer needed","If it should be per-machine, template the config (e.g. gitignore a local override)"],"exampleFix":"// before\ninstructionsAppendix: \"./AGENTS_APPENDIX.local.md\" // missing on this machine\n\n// after\ninstructionsAppendix: existsSync(\"./AGENTS_APPENDIX.local.md\") ? \"./AGENTS_APPENDIX.local.md\" : undefined","handlingStrategy":"validation","validationCode":"import { existsSync } from \"node:fs\";\nconst appendix = config.instructionsAppendix;\nif (appendix && !existsSync(resolve(cwd, appendix))) config.instructionsAppendix = undefined;","typeGuard":null,"tryCatchPattern":"try { await launch(cfg); } catch (e) { if (e instanceof Error && e.message.startsWith(\"launch instructions file not found\")) { /* fix path or drop setting */ } throw e; }","preventionTips":["Use repo-relative or absolute paths for instruction appendix files","Commit shared instruction files; gitignore only per-machine overrides","Validate configured file paths at startup in wrapper scripts"],"tags":["file-not-found","config","launch-instructions"],"backgroundTag":"config-file-not-found","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}