p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/src/github/client.ts

@@ -44,6 +44,8 @@ function createGitHubApiError(
 
 export interface GitHubClientOptions {
   token: string;
+  /** Optional per-request timeout for REST/GraphQL fetch calls. */
+  timeoutMs?: number;
 }
 
 export interface GitHubPullRequest {
@@ -185,6 +187,8 @@ export interface GitHubPullRequestListItem {
   html_url: string;
   state: string;
   created_at: string;
+  body?: string | null;
+  merged_at?: string | null;
   head: { ref: string; sha: string };
   base: { ref: string };
 }
@@ -194,6 +198,7 @@ export interface GitHubCompareResult {
   ahead_by: number;
   behind_by: number;
   commits: Array<{ sha: string; commit: { message: string } }>;
+  files?: Array<{ filename: string; status?: string }>;
 }
 
 export interface GitHubGitRef {
@@ -231,18 +236,61 @@ export interface GitHubCreatePullRequestResponse {
   base: { ref: string };
 }
 
+export interface GitHubWorkflowRun {
+  id: number;
+  status: "queued" | "in_progress" | "completed" | "waiting" | "requested" | "pending";
+  conclusion: "success" | "failure" | "cancelled" | "skipped" | "timed_out" | "action_required" | "neutral" | "stale" | null;
+  html_url: string;
+  created_at: string;
+  event?: string;
+  name?: string;
+  display_title?: string;
+}
+
+export interface GitHubGitBlobContent {
+  sha: string;
+  content: string;
+  encoding: string;
+}
+
 const GITHUB_API = "https://api.github.com";
 
 export class GitHubClient {
   private readonly token: string;
+  private readonly timeoutMs?: number;
 
   constructor(options: GitHubClientOptions) {
     this.token = options.token;
+    this.timeoutMs = options.timeoutMs;
+  }
+
+  private requestSignal(external?: AbortSignal): AbortSignal | undefined {
+    const signals: AbortSignal[] = [];
+    if (
+      typeof this.timeoutMs === "number" &&
+      Number.isFinite(this.timeoutMs) &&
+      this.timeoutMs > 0
+    ) {
+      signals.push(AbortSignal.timeout(this.timeoutMs));
+    }
+    if (external) {
+      signals.push(external);
+    }
+    if (signals.length === 0) {
+      return undefined;
+    }
+    if (signals.length === 1) {
+      return signals[0];
+    }
+    if (typeof AbortSignal.any === "function") {
+      return AbortSignal.any(signals);
+    }
+    return signals[0];
   }
 
   private async request<T>(
     path: string,
-    init?: { method?: string; body?: unknown },
+    init?: { method?: string; body?: unknown; signal?: AbortSignal },
   ): Promise<T> {
     const response = await fetch(`${GITHUB_API}${path}`, {
       method: init?.method ?? "GET",
@@ -253,6 +301,7 @@ export class GitHubClient {
         ...(init?.body ? { "Content-Type": "application/json" } : {}),
       },
       body: init?.body ? JSON.stringify(init.body) : undefined,
+      signal: this.requestSignal(init?.signal),
     });
 
     if (!response.ok) {
@@ -281,6 +330,7 @@ export class GitHubClient {
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ query, variables }),
+      signal: this.requestSignal(),
     });
 
     if (!response.ok) {
@@ -349,14 +399,22 @@ export class GitHubClient {
     owner: string,
     repo: string,
     branch: string,
+    options?: { signal?: AbortSignal },
   ): Promise<GitHubGitRef> {
     return this.request<GitHubGitRef>(
       `/repos/${owner}/${repo}/git/ref/heads/${encodeURIComponent(branch)}`,
+      { signal: options?.signal },
     );
   }
 
-  async getRepository(owner: string, repo: string): Promise<GitHubRepository> {
-    return this.request<GitHubRepository>(`/repos/${owner}/${repo}`);
+  async getRepository(
+    owner: string,
+    repo: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<GitHubRepository> {
+    return this.request<GitHubRepository>(`/repos/${owner}/${repo}`, {
+      signal: options?.signal,
+    });
   }
 
   async getRepositoryById(repositoryId: number): Promise<GitHubRepository> {
@@ -524,15 +582,58 @@ export class GitHubClient {
     });
   }
 
+  async getActionsVariable(
+    owner: string,
+    repo: string,
+    name: string,
+  ): Promise<{ name: string; value: string } | null> {
+    try {
+      return await this.request<{ name: string; value: string }>(
+        `/repos/${owner}/${repo}/actions/variables/${encodeURIComponent(name)}`,
+      );
+    } catch (error) {
+      if (error instanceof GitHubApiError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async upsertActionsVariable(
+    owner: string,
+    repo: string,
+    name: string,
+    value: string,
+  ): Promise<"created" | "updated"> {
+    const existing = await this.getActionsVariable(owner, repo, name);
+    if (existing) {
+      await this.request(
+        `/repos/${owner}/${repo}/actions/variables/${encodeURIComponent(name)}`,
+        {
+          method: "PATCH",
+          body: { name, value },
+        },
+      );
+      return "updated";
+    }
+    await this.request(`/repos/${owner}/${repo}/actions/variables`, {
+      method: "POST",
+      body: { name, value },
+    });
+    return "created";
+  }
+
   async getRepositoryContent(
     owner: string,
     repo: string,
     path: string,
     ref: string,
+    options?: { signal?: AbortSignal },
   ): Promise<GitHubRepositoryContent | null> {
     try {
       return await this.request<GitHubRepositoryContent>(
         `/repos/${owner}/${repo}/contents/${path}?ref=${encodeURIComponent(ref)}`,
+        { signal: options?.signal },
       );
     } catch (error) {
       if (error instanceof GitHubApiError && error.status === 404) {
@@ -601,12 +702,16 @@ export class GitHubClient {
   async updateUserRepository(input: {
     owner: string;
     repo: string;
-    description: string;
+    description?: string;
+    default_branch?: string;
   }): Promise<GitHubRepository> {
     return this.request<GitHubRepository>(`/repos/${input.owner}/${input.repo}`, {
       method: "PATCH",
       body: {
-        description: input.description,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.default_branch !== undefined
+          ? { default_branch: input.default_branch }
+          : {}),
       },
     });
   }
@@ -787,6 +892,100 @@ export class GitHubClient {
       `/repos/${owner}/${repo}/pulls?${params.toString()}`,
     );
   }
+
+  async updatePullRequest(
+    owner: string,
+    repo: string,
+    pullNumber: number,
+    patch: { title?: string; body?: string },
+  ): Promise<void> {
+    await this.request(`/repos/${owner}/${repo}/pulls/${pullNumber}`, {
+      method: "PATCH",
+      body: patch,
+    });
+  }
+
+  async createWorkflowDispatch(
+    owner: string,
+    repo: string,
+    workflowIdOrFileName: string,
+    ref: string,
+    inputs?: Record<string, string>,
+  ): Promise<void> {
+    const workflowId = encodeURIComponent(workflowIdOrFileName);
+    await this.request(
+      `/repos/${owner}/${repo}/actions/workflows/${workflowId}/dispatches`,
+      {
+        method: "POST",
+        body: {
+          ref,
+          ...(inputs ? { inputs } : {}),
+        },
+      },
+    );
+  }
+
+  async getWorkflowRun(
+    owner: string,
+    repo: string,
+    runId: number,
+  ): Promise<GitHubWorkflowRun> {
+    const response = await this.request<{
+      id: number;
+      status: GitHubWorkflowRun["status"];
+      conclusion: GitHubWorkflowRun["conclusion"];
+      html_url: string;
+      created_at: string;
+      event?: string;
+      name?: string;
+      display_title?: string;
+    }>(`/repos/${owner}/${repo}/actions/runs/${runId}`);
+    return {
+      id: response.id,
+      status: response.status,
+      conclusion: response.conclusion,
+      html_url: response.html_url,
+      created_at: response.created_at,
+      event: response.event,
+      name: response.name,
+      display_title: response.display_title,
+    };
+  }
+
+  async listWorkflowRuns(
+    owner: string,
+    repo: string,
+    workflowIdOrFileName: string,
+    options: {
+      branch?: string;
+      event?: string;
+      perPage?: number;
+    } = {},
+  ): Promise<GitHubWorkflowRun[]> {
+    const params = new URLSearchParams();
+    params.set("per_page", String(options.perPage ?? 10));
+    if (options.branch) {
+      params.set("branch", options.branch);
+    }
+    if (options.event) {
+      params.set("event", options.event);
+    }
+    const workflowId = encodeURIComponent(workflowIdOrFileName);
+    const response = await this.request<{ workflow_runs: GitHubWorkflowRun[] }>(
+      `/repos/${owner}/${repo}/actions/workflows/${workflowId}/runs?${params.toString()}`,
+    );
+    return response.workflow_runs ?? [];
+  }
+
+  async getGitBlob(
+    owner: string,
+    repo: string,
+    blobSha: string,
+  ): Promise<GitHubGitBlobContent> {
+    return this.request<GitHubGitBlobContent>(
+      `/repos/${owner}/${repo}/git/blobs/${blobSha}`,
+    );
+  }
 }
 
 export async function pingGitHub(token: string): Promise<string> {

package/workspace-snapshot/files/src/gui/configure-health.ts

@@ -133,7 +133,7 @@ export async function waitForConfigureServer(
   timeoutMs: number,
 ): Promise<void> {
   const deadline = Date.now() + timeoutMs;
-  const healthUrl = `${baseUrl.replace(/\/$/, "")}/settings/configure`;
+  const healthUrl = `${baseUrl.replace(/\/$/, "")}/`;
 
   while (Date.now() < deadline) {
     try {
@@ -149,7 +149,7 @@ export async function waitForConfigureServer(
   }
 
   throw new Error(
-    `Configure GUI did not become reachable at ${healthUrl} within ${timeoutMs}ms`,
+    `Harness GUI did not become reachable at ${healthUrl} within ${timeoutMs}ms`,
   );
 }
 

package/workspace-snapshot/files/src/gui/repo-root.ts

@@ -17,6 +17,25 @@ export function resolveHarnessRepoRoot(startDir = process.cwd()): string {
     return path.resolve(fromWorkspace);
   }
 
+  return resolveHarnessSourceRoot(startDir);
+}
+
+/** Workspace for setup files, observability state, and operator-local artifacts. */
+export function resolveHarnessWorkspaceDir(startDir = process.cwd()): string {
+  const fromWorkspace = process.env[P_DEV_HOME_ENV]?.trim();
+  if (fromWorkspace) {
+    return path.resolve(fromWorkspace);
+  }
+
+  const fromEnv = process.env.HARNESS_REPO_ROOT?.trim();
+  if (fromEnv) {
+    return path.resolve(fromEnv);
+  }
+
+  return resolveHarnessSourceRoot(startDir);
+}
+
+export function resolveHarnessSourceRoot(startDir: string): string {
   let current = path.resolve(startDir);
   while (true) {
     const packageJsonPath = path.join(current, "package.json");
@@ -40,7 +59,7 @@ export function resolveHarnessRepoRoot(startDir = process.cwd()): string {
   }
 
   throw new Error(
-    `Could not resolve harness repo root from ${startDir}. Set HARNESS_REPO_ROOT or run harness:gui from the repo.`,
+    `Could not resolve harness source root from ${startDir}. Set HARNESS_REPO_ROOT or run harness:gui from the repo.`,
   );
 }
 

package/workspace-snapshot/files/src/gui/start-configure-stable.ts

@@ -16,12 +16,14 @@ import {
   stopChildProcess,
   stopStaleGuiServers,
 } from "./dev-server-process.js";
-import { resolveHarnessRepoRoot } from "./repo-root.js";
+import { P_DEV_OBSERVABILITY_NONCE_ENV } from "../observability/constants.js";
+import { resolveSourceGuiObservabilityNonce } from "../observability/session-handoff.js";
+import { resolveHarnessSourceRoot } from "./repo-root.js";
 
 const STARTUP_TIMEOUT_MS = 90_000;
 
 async function main(): Promise<void> {
-  const repoRoot = resolveHarnessRepoRoot(
+  const repoRoot = resolveHarnessSourceRoot(
     path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."),
   );
   const guiDir = path.join(repoRoot, "apps", "gui");
@@ -81,6 +83,7 @@ function spawnNextDev(repoRoot: string, guiDir: string) {
     ".bin",
     process.platform === "win32" ? "next.cmd" : "next",
   );
+  const observabilityNonce = resolveSourceGuiObservabilityNonce();
 
   console.log(
     `Starting Configure GUI at http://${STABLE_GUI_HOST}:${STABLE_GUI_PORT}/settings/configure`,
@@ -97,6 +100,7 @@ function spawnNextDev(repoRoot: string, guiDir: string) {
         HARNESS_REPO_ROOT: repoRoot,
         HARNESS_GUI_HOST: STABLE_GUI_HOST,
         HARNESS_GUI_PORT: String(STABLE_GUI_PORT),
+        [P_DEV_OBSERVABILITY_NONCE_ENV]: observabilityNonce,
       },
     },
   );

package/workspace-snapshot/files/src/gui/start-gui.ts

@@ -3,8 +3,10 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveAvailableGuiPort } from "./port.js";
+import { P_DEV_OBSERVABILITY_NONCE_ENV } from "../observability/constants.js";
+import { resolveSourceGuiObservabilityNonce } from "../observability/session-handoff.js";
 
-import { resolveHarnessRepoRoot } from "./repo-root.js";
+import { resolveHarnessSourceRoot } from "./repo-root.js";
 
 interface CliOptions {
   port?: number;
@@ -73,11 +75,11 @@ async function main(): Promise<void> {
     port: cli.port,
   });
 
-  const repoRoot = resolveHarnessRepoRoot(
+  const repoRoot = resolveHarnessSourceRoot(
     path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."),
   );
   const guiDir = path.join(repoRoot, "apps", "gui");
-  const route = cli.route ?? "/settings/configure";
+  const route = cli.route ?? "/";
   const url = `http://${host}:${port}${route}`;
 
   if (port !== requestedPort) {
@@ -95,6 +97,8 @@ async function main(): Promise<void> {
     process.platform === "win32" ? "next.cmd" : "next",
   );
 
+  const observabilityNonce = resolveSourceGuiObservabilityNonce();
+
   const child = spawn(
     nextBin,
     ["dev", "--hostname", host, "--port", String(port)],
@@ -106,6 +110,7 @@ async function main(): Promise<void> {
         HARNESS_REPO_ROOT: repoRoot,
         HARNESS_GUI_HOST: host,
         HARNESS_GUI_PORT: String(port),
+        [P_DEV_OBSERVABILITY_NONCE_ENV]: observabilityNonce,
       },
     },
   );

package/workspace-snapshot/files/src/linear/client.ts

@@ -6,12 +6,20 @@ export interface LinearIssueSnapshot {
   title: string;
   description: string | null;
   status: string | null;
+  projectId: string | null;
   projectName: string | null;
   teamName: string | null;
+  teamKey: string | null;
   teamId: string | null;
   url: string | null;
 }
 
+/** Derive Linear team key from issue identifier (e.g. FRE-1 → FRE). */
+export function teamKeyFromIssueIdentifier(identifier: string): string | null {
+  const match = identifier.trim().match(/^([A-Za-z][A-Za-z0-9]*)-\d+$/);
+  return match?.[1] ?? null;
+}
+
 export async function fetchLinearIssue(
   issueKey: string,
   apiKey: string,
@@ -35,8 +43,10 @@ export async function fetchLinearIssue(
     title: issue.title,
     description: issue.description ?? null,
     status: state?.name ?? null,
+    projectId: project?.id ?? null,
     projectName: project?.name ?? null,
     teamName: team?.name ?? null,
+    teamKey: team?.key ?? teamKeyFromIssueIdentifier(issue.identifier),
     teamId: team?.id ?? null,
     url: issue.url ?? null,
   };

package/workspace-snapshot/files/src/linear/comments.ts

@@ -23,6 +23,7 @@ import {
   type PhaseStartPhase,
 } from "./phase-labels.js";
 import { appendExecutionEnvironmentMetadataLines } from "../runner/execution-environment.js";
+import type { BuilderThreadMarkerEvidence } from "../runner/builder-thread-types.js";
 
 export type { PhaseStartPhase, HarnessErrorPhase };
 
@@ -32,6 +33,13 @@ export interface HarnessCommentFooterInput {
   runId: string;
   cursorAgentId?: string;
   cursorRunId?: string;
+  builderAgentId?: string;
+  builderThreadGeneration?: number;
+  builderThreadAction?: string;
+  builderOriginRunId?: string;
+  builderThreadIdempotencyKey?: string;
+  previousBuilderAgentId?: string;
+  builderThreadReplacementReason?: string;
   model: string;
   promptVersion: string;
   targetRepo: string;
@@ -117,6 +125,29 @@ function buildHarnessMetadataLines(
   if (input.cursorRunId) {
     lines.push(`cursor_run_id: ${input.cursorRunId}`);
   }
+  if (input.builderAgentId) {
+    lines.push(`builder_agent_id: ${input.builderAgentId}`);
+  }
+  if (input.builderThreadGeneration !== undefined) {
+    lines.push(`builder_thread_generation: ${input.builderThreadGeneration}`);
+  }
+  if (input.builderThreadAction) {
+    lines.push(`builder_thread_action: ${input.builderThreadAction}`);
+  }
+  if (input.builderOriginRunId) {
+    lines.push(`builder_origin_run_id: ${input.builderOriginRunId}`);
+  }
+  if (input.builderThreadIdempotencyKey) {
+    lines.push(`builder_thread_idempotency_key: ${input.builderThreadIdempotencyKey}`);
+  }
+  if (input.previousBuilderAgentId) {
+    lines.push(`previous_builder_agent_id: ${input.previousBuilderAgentId}`);
+  }
+  if (input.builderThreadReplacementReason) {
+    lines.push(
+      `builder_thread_replacement_reason: ${input.builderThreadReplacementReason}`,
+    );
+  }
   lines.push(
     `model: ${input.model}`,
     `prompt_version: ${input.promptVersion}`,
@@ -889,3 +920,24 @@ export function parsePrNumberFromUrl(prUrl: string): string | null {
   const match = prUrl.match(/\/pull\/(\d+)/);
   return match?.[1] ?? null;
 }
+
+export function withBuilderThreadMarkerEvidence<
+  T extends HarnessCommentFooterInput,
+>(footer: T, evidence: BuilderThreadMarkerEvidence): T {
+  return {
+    ...footer,
+    builderAgentId: evidence.builderAgentId ?? footer.builderAgentId,
+    builderThreadGeneration:
+      evidence.builderThreadGeneration ?? footer.builderThreadGeneration,
+    builderThreadAction:
+      evidence.builderThreadAction ?? footer.builderThreadAction,
+    builderOriginRunId: evidence.builderOriginRunId ?? footer.builderOriginRunId,
+    builderThreadIdempotencyKey:
+      evidence.builderThreadIdempotencyKey ?? footer.builderThreadIdempotencyKey,
+    previousBuilderAgentId:
+      evidence.previousBuilderAgentId ?? footer.previousBuilderAgentId,
+    builderThreadReplacementReason:
+      evidence.builderThreadReplacementReason ??
+      footer.builderThreadReplacementReason,
+  };
+}

package/workspace-snapshot/files/src/linear/issue-query.ts

@@ -6,6 +6,7 @@ export interface LinearIssueListItem {
   identifier: string;
   title: string;
   status: string | null;
+  projectId: string | null;
   projectName: string | null;
   teamId: string | null;
   url: string | null;
@@ -46,6 +47,7 @@ export async function listIssuesByStatus(
       identifier: issue.identifier,
       title: issue.title,
       status: issueStatus,
+      projectId: project?.id ?? null,
       projectName,
       teamId: team.id,
       url: issue.url ?? null,
@@ -62,8 +64,10 @@ export function toIssueSnapshot(item: LinearIssueListItem): LinearIssueSnapshot
     title: item.title,
     description: null,
     status: item.status,
+    projectId: item.projectId,
     projectName: item.projectName,
     teamName: null,
+    teamKey: null,
     teamId: item.teamId,
     url: item.url,
   };

package/workspace-snapshot/files/src/linear/markers.ts

@@ -4,6 +4,13 @@ export interface HarnessMarkers {
   runId?: string;
   cursorAgentId?: string;
   cursorRunId?: string;
+  builderAgentId?: string;
+  builderThreadGeneration?: string;
+  builderThreadAction?: string;
+  builderOriginRunId?: string;
+  builderThreadIdempotencyKey?: string;
+  previousBuilderAgentId?: string;
+  builderThreadReplacementReason?: string;
   model?: string;
   promptVersion?: string;
   targetRepo?: string;
@@ -91,6 +98,27 @@ function parseHarnessMarkerLines(block: string): HarnessMarkers {
       case "cursor_run_id":
         markers.cursorRunId = value;
         break;
+      case "builder_agent_id":
+        markers.builderAgentId = value;
+        break;
+      case "builder_thread_generation":
+        markers.builderThreadGeneration = value;
+        break;
+      case "builder_thread_action":
+        markers.builderThreadAction = value;
+        break;
+      case "builder_origin_run_id":
+        markers.builderOriginRunId = value;
+        break;
+      case "builder_thread_idempotency_key":
+        markers.builderThreadIdempotencyKey = value;
+        break;
+      case "previous_builder_agent_id":
+        markers.previousBuilderAgentId = value;
+        break;
+      case "builder_thread_replacement_reason":
+        markers.builderThreadReplacementReason = value;
+        break;
       case "model":
         markers.model = value;
         break;