Brief app-started sessions about the graph too

The briefing that teaches a session to fan work out with `graphcode
node create` was only delivered by the daemon's launcher — and a
turn-based loop never starts there, so opened from the app it had never
heard of the CLI and improvised: a Copilot loop asked to create more
loops reached for its own sub-agents instead. GhosttyTerminalView now
delivers the briefing the same per-backend way ZmxSessionLauncher does
(Claude via --append-system-prompt-file, Copilot/Codex via --add-dir
plus a pointer on the opening prompt), with the pointer riding inside
the prompt env var where prose needs no shell quoting.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: scgopi

graphcode/Sources/Features/LoopWorkspace/LoopWorkspaceView.swift

@@ -189,6 +189,9 @@ struct LoopWorkspaceView: View {
       // A node without its own worktree yet still belongs to a project — its shells
       // should open there, not wherever the app process happened to launch from.
       workingDirectory: store.node.worktreeBinding?.worktreePath ?? store.projectPath,
+      // The graph's own project, for the session briefing — deliberately not the
+      // worktree, whose path names a graph that doesn't exist.
+      projectPath: ref.launchesClaudeCode ? store.projectPath : nil,
       // Only *one* surface in the whole workspace is the live one: the showing tab's
       // focused pane. Every other surface stays mounted and must not hold the keyboard —
       // including the other half of this tab's own split, which is what stops both panes

graphcode/Sources/Infrastructure/Ghostty/GhosttyTerminalView.swift

@@ -43,6 +43,12 @@ struct GhosttyTerminalView: NSViewRepresentable {
   /// opened before the daemon got to it, or with `zmx` not installed.
   var initialPrompt: String?
   let workingDirectory: String?
+  /// The project whose graph this loop belongs to — what the session's briefing tells it
+  /// to create further loops *in*. Distinct from `workingDirectory`, which is the
+  /// worktree when the node has one; a briefing built from the worktree path would have
+  /// the agent extending a graph that doesn't exist. `nil` for plain-shell surfaces,
+  /// which get no briefing.
+  var projectPath: String?
   /// Whether this is *the* surface the user is typing into — its tab is the one on
   /// screen **and** it is that tab's focused pane. Every tab stays mounted and a split
   /// has two live terminals, so without this the keyboard can end up parked on a surface
@@ -69,10 +75,13 @@ struct GhosttyTerminalView: NSViewRepresentable {
   func makeNSView(context: Context) -> TerminalSurfaceHostView {
     let host = TerminalSurfaceHostView()
     let view = TerminalSurfaceStore.shared.surface(for: surfaceID) {
-      GhosttyTerminalNSView(
-        command: command,
+      // Written once per surface build, not held: like `ZmxSessionLauncher`, rewriting
+      // on launch means the briefing never goes stale against an upgraded graphcode.
+      let briefingFile = self.briefingFile()
+      return GhosttyTerminalNSView(
+        command: command(briefingFile: briefingFile),
         workingDirectory: workingDirectory,
-        environment: initialPrompt.map { [Self.promptVariable: $0] } ?? [:])
+        environment: sessionEnvironment(briefingFile: briefingFile))
     }
     apply(to: view)
     host.adopt(view)
@@ -127,7 +136,9 @@ struct GhosttyTerminalView: NSViewRepresentable {
   /// `settings` is a parameter rather than a read inside the body so a test can state what
   /// a human chose and check what the shell is told — the omission this fixes was
   /// invisible precisely because there was nothing to assert against.
-  func agentCommand(settings: GraphcodeSettings = GraphcodeSettingsStore.load()) -> [String]? {
+  func agentCommand(
+    settings: GraphcodeSettings = GraphcodeSettingsStore.load(), briefingFile: URL? = nil
+  ) -> [String]? {
     guard let executable = backend.executableName else { return nil }
     let tier = ModelTier.resolved(
       pinned: pinnedModelTier, for: loopType, autoSelecting: settings.autoSelectsModel)
@@ -138,16 +149,54 @@ struct GhosttyTerminalView: NSViewRepresentable {
     var parts = ["exec", executable]
     if !model.isEmpty { parts.append(model) }
     if !permissions.isEmpty { parts.append(permissions) }
+    // The briefing, delivered the same per-backend way `BackendCommand.launchArguments`
+    // delivers it for a daemon-started session — before this, only daemon-started loops
+    // knew they could fan out, and a turn-based loop (which only ever starts here) asked
+    // to create more loops improvised with its backend's own sub-agents instead (the
+    // Copilot shape of issue #2). Claude takes the file itself as a flag; Copilot and
+    // Codex are granted the directory and pointed at the file inside their opening
+    // prompt — see `sessionEnvironment`, where the pointer rides in the env var and so
+    // needs no shell quoting.
+    if let briefingFile {
+      switch backend {
+      case .claudeCode:
+        parts.append("--append-system-prompt-file \(briefingFile.path)")
+      case .copilotCLI, .codex:
+        parts.append("--add-dir \(briefingFile.deletingLastPathComponent().path)")
+      }
+    }
     if !prompt.isEmpty {
       if backend == .copilotCLI { parts.append("--interactive") }
       parts.append(prompt)
     }
     return ["/bin/zsh", "-i", "-l", "-c", parts.joined(separator: " ")]
   }
 
-  private var command: [String] {
+  /// Where the graph briefing for this session landed, or `nil` when it shouldn't get
+  /// one: a plain shell, a surface with no opening prompt to carry the pointer, a
+  /// briefing the human switched off, or nowhere to write.
+  func briefingFile(settings: GraphcodeSettings = GraphcodeSettingsStore.load()) -> URL? {
+    guard launchesClaudeCode, initialPrompt != nil, settings.briefsSessionsAboutTheGraph
+    else { return nil }
+    return SessionBriefing.write(projectPath: projectPath)
+  }
+
+  /// What rides into the session through the environment: the opening prompt, prefixed
+  /// for Copilot and Codex with the pointer at the briefing file. In the env var rather
+  /// than on the command line because the pointer is prose — inside `"$VAR"` it needs no
+  /// quoting and cannot break the shell string the command is joined into. Claude's
+  /// prompt stays untouched: its briefing arrives via `--append-system-prompt-file`.
+  func sessionEnvironment(briefingFile: URL?) -> [String: String] {
+    guard var prompt = initialPrompt else { return [:] }
+    if backend != .claudeCode, let briefingFile {
+      prompt = "\(SessionBriefing.pointer(toBriefingAt: briefingFile.path)) \(prompt)"
+    }
+    return [Self.promptVariable: prompt]
+  }
+
+  private func command(briefingFile: URL?) -> [String] {
     let shell = ["/bin/zsh", "-l"]
-    guard let agentCommand = agentCommand() else {
+    guard let agentCommand = agentCommand(briefingFile: briefingFile) else {
       // A backend graphcode can't launch gets a plain shell rather than the wrong agent.
       // `canHost` already refuses to create such a node, so this is unreachable in
       // practice and deliberately inert if it ever isn't.

graphcode/Tests/AttachedSessionBriefingTests.swift

@@ -0,0 +1,84 @@
+import Foundation
+import GraphcodeKit
+import Testing
+
+@testable import graphcode
+
+/// An app-started session gets the same graph briefing a daemon-started one does.
+///
+/// The gap this closes: `ZmxSessionLauncher` delivered the briefing for every backend,
+/// but `GhosttyTerminalView` — the *only* launcher a turn-based loop ever has, since it
+/// doesn't start unattended — delivered nothing. A turn-based Copilot loop asked to fan
+/// work out had never heard of `graphcode node create` and improvised with its own
+/// sub-agents instead.
+@Suite
+struct AttachedSessionBriefingTests {
+  private let briefing = URL(fileURLWithPath: "/tmp/briefings/proj/AGENTS.md")
+
+  private func surface(
+    _ backend: CLISessionBackendKind, launchesClaudeCode: Bool = true,
+    initialPrompt: String? = "go"
+  ) -> GhosttyTerminalView {
+    GhosttyTerminalView(
+      surfaceID: UUID(), sessionName: "s", launchesClaudeCode: launchesClaudeCode,
+      backend: backend, initialPrompt: initialPrompt, workingDirectory: nil,
+      projectPath: "/tmp/proj", onProcessExited: { _ in })
+  }
+
+  private func shellCommand(_ backend: CLISessionBackendKind) -> String {
+    surface(backend).agentCommand(settings: GraphcodeSettings(), briefingFile: briefing)?
+      .last ?? ""
+  }
+
+  @Test
+  func claudeTakesTheBriefingAsASystemPromptFile() {
+    #expect(shellCommand(.claudeCode).contains("--append-system-prompt-file \(briefing.path)"))
+    // And its prompt is not the delivery mechanism, so it stays untouched.
+    let environment = surface(.claudeCode).sessionEnvironment(briefingFile: briefing)
+    #expect(environment["GRAPHCODE_TRIGGER_PROMPT"] == "go")
+  }
+
+  @Test
+  func copilotIsGrantedTheDirectoryAndPointedAtTheFile() {
+    let command = shellCommand(.copilotCLI)
+    // `--add-dir` is the half that is easy to miss: Copilot verifies paths, so without
+    // it the pointer reads as the agent ignoring an instruction (issue #2's shape).
+    #expect(command.contains("--add-dir /tmp/briefings/proj"))
+    #expect(command.contains("--interactive"))
+
+    // The pointer rides inside the env var, where prose needs no shell quoting.
+    let environment = surface(.copilotCLI).sessionEnvironment(briefingFile: briefing)
+    let prompt = environment["GRAPHCODE_TRIGGER_PROMPT"] ?? ""
+    #expect(prompt.contains(briefing.path))
+    #expect(prompt.hasSuffix(" go"))
+  }
+
+  @Test
+  func codexRidesTheSameWayCopilotDoes() {
+    #expect(shellCommand(.codex).contains("--add-dir /tmp/briefings/proj"))
+    let prompt =
+      surface(.codex).sessionEnvironment(briefingFile: briefing)[
+        "GRAPHCODE_TRIGGER_PROMPT"] ?? ""
+    #expect(prompt.contains(briefing.path))
+  }
+
+  @Test
+  func noBriefingMeansTheCommandAndPromptOfBefore() {
+    let command =
+      surface(.copilotCLI).agentCommand(
+        settings: GraphcodeSettings(), briefingFile: nil)?.last ?? ""
+    #expect(!command.contains("--add-dir"))
+    let environment = surface(.copilotCLI).sessionEnvironment(briefingFile: nil)
+    #expect(environment["GRAPHCODE_TRIGGER_PROMPT"] == "go")
+  }
+
+  @Test
+  func surfacesThatShouldNotBeBriefedGetNoFile() {
+    // A plain shell is not a loop; a surface with no opening prompt has nothing to hang
+    // the pointer on; and the human can switch briefing off entirely.
+    let disabled = GraphcodeSettings(briefsSessionsAboutTheGraph: false)
+    #expect(surface(.claudeCode, launchesClaudeCode: false).briefingFile() == nil)
+    #expect(surface(.copilotCLI, initialPrompt: nil).briefingFile() == nil)
+    #expect(surface(.copilotCLI).briefingFile(settings: disabled) == nil)
+  }
+}