feat: manual PR fallback and branch-aligned create-pr flow (#69)

* Slack: manual PR fallback with Create PR button (#21)

* Add Slack manual PR fallback with Create PR button

* Address PR review feedback for manual PR flow

* Harden manual PR fallback and artifact parsing

* refactor: isolate github provider factory and push-spec builders (#22)

* feat: align create-pr head branch with pushed branch (#23)

* refactor: isolate github provider factory and push-spec builders

* feat: align create-pr branch flow with pushed branch

* fix: tighten Slack manual PR artifact detection (#24)

* refactor: isolate github provider factory and push-spec builders

* feat: align create-pr branch flow with pushed branch

* fix: tighten slack manual-pr artifact detection

* fix: address provider factory and push-spec default review feedback

Author: ColeMurray

packages/control-plane/README.md

@@ -70,6 +70,18 @@ The control plane provides:
 | `/sessions/:id/archive`      | POST      | Archive session          |
 | `/sessions/:id/unarchive`    | POST      | Unarchive session        |
 
+### Create PR Payload
+
+`POST /sessions/:id/pr` accepts:
+
+- `title` (required)
+- `body` (required)
+- `baseBranch` (optional)
+- `headBranch` (optional)
+
+When `headBranch` is omitted, control-plane resolves it from session state and finally falls back to
+the generated `open-inspect/<session>` branch.
+
 ### Repositories
 
 | Endpoint                           | Method | Description          |
@@ -187,6 +199,10 @@ The system uses two types of GitHub tokens:
 | GitHub App Token | Clone, push | Yes (ephemeral)  | All repos where App is installed |
 | User OAuth Token | Create PRs  | No (server-only) | User's accessible repos          |
 
+If a `create-pr` request is triggered by a participant without a user OAuth token (for example,
+Slack-created sessions), the control-plane still pushes the branch with the GitHub App token and
+returns a manual GitHub `pull/new` URL instead of failing the request.
+
 ### Why This Matters
 
 - **No per-user repo access validation**: When a session is created, the system does not verify that

packages/control-plane/src/router.ts

@@ -835,12 +835,26 @@ async function handleCreatePR(
     title: string;
     body: string;
     baseBranch?: string;
+    headBranch?: string;
   };
 
-  if (!body.title || !body.body) {
+  if (
+    typeof body.title !== "string" ||
+    typeof body.body !== "string" ||
+    body.title.trim().length === 0 ||
+    body.body.trim().length === 0
+  ) {
     return error("title and body are required");
   }
 
+  if (body.baseBranch != null && typeof body.baseBranch !== "string") {
+    return error("baseBranch must be a string");
+  }
+
+  if (body.headBranch != null && typeof body.headBranch !== "string") {
+    return error("headBranch must be a string");
+  }
+
   const doId = env.SESSION.idFromName(sessionId);
   const stub = env.SESSION.get(doId);
 
@@ -854,6 +868,7 @@ async function handleCreatePR(
           title: body.title,
           body: body.body,
           baseBranch: body.baseBranch,
+          headBranch: body.headBranch,
         }),
       },
       ctx