Function readSingleProjectContextInstructions

src/node/services/systemMessage.ts:380–421

(
  metadata: WorkspaceMetadata,
  runtime: Runtime,
  workspaceRootPath: string
)

}

async function readSingleProjectContextInstructions(
  metadata: WorkspaceMetadata,
  runtime: Runtime,
  workspaceRootPath: string
): Promise<InstructionSet[]> {
  // Read parent + sub-project AGENTS.md from the workspace's *own* checkout
  // (via the runtime). For worktree/SSH/Docker flows the parent project's host
  // path is a different checkout than the workspace branch — mixing the two
  // would inject contradictory or stale guidance and prevent workspace-branch
  // edits from overriding parent guidance. The workspace root is by
  // construction the parent project's checkout, and any registered
  // sub-project's relative path is stable across checkouts of the same repo.
  //
  // `workspaceRootPath` is the parent project's checkout root — *without* the
  // sub-project segment appended (see `resolveWorkspaceRootPath`). The
  // sub-project's AGENTS.md is read at `<root>/<subProjectRelativePath>`.
  const subProjectRelativePath = metadata.subProjectPath
    ? deriveSubProjectRelativePath(metadata.projectPath, metadata.subProjectPath)
    : null;

  // path.relative emits host-native separators (e.g., "packages\\api" on Windows),
  // but SSH/Docker/devcontainer runtimes read files via POSIX paths. Normalize to
  // forward slashes and let the runtime joiner produce a runtime-correct path.
  const subProjectInstructionsDir = subProjectRelativePath
    ? runtime.normalizePath(subProjectRelativePath.replace(/\\/g, "/"), workspaceRootPath)
    : null;

  const [parentInstructions, subProjectInstructions] = await Promise.all([
    readInstructionSetFromRuntime(runtime, workspaceRootPath, INSTRUCTION_SCOPE.WORKSPACE),
    subProjectInstructionsDir
      ? readInstructionSetFromRuntime(
          runtime,
          subProjectInstructionsDir,
          INSTRUCTION_SCOPE.SUBPROJECT
        )
      : Promise.resolve(null),
  ]);

  return [parentInstructions, subProjectInstructions].filter(
    (set): set is InstructionSet => set != null && set.combinedContent.trim().length > 0
  );
}

/**
 * Compute the path of `subProjectPath` relative to `projectPath` for use under