test(runner-e2e): gate completion briefs inside the run's own task directory (#19475)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent Chat returns delegated-task completions to the chat that
started them, and the runner E2E `completion-updates` suite checks this
with real providers
> - The restart cell
(`completion-updates.runner-codex.local.handoff-completion-restart`)
failed before its server restart with "Timed out waiting for worker
waiting while originating chat is idle"
> - Since project-optional task workspaces (#15749), a task in a project
without a workspace runs in its isolated task directory. A native chat
runs in its isolated conversation directory. Native Codex can read only
that directory.
> - The fixture still wrote its brief wait scripts into the managed
project workspace and the agent home. Codex got EPERM on both scripts,
wrote the note from the task record, and finished. The worker never
reached the gate, so the setup poll timed out.
> - This pull request makes the waits name only cwd-relative files and
publishes each brief into the run's own isolated task directory
> - The benefit is that the restart cell reaches its real boundary again
(durable Done, source provider held at the gate, server restart) and
tests restart recovery instead of a stale fixture path

## Linked Issues or Issue Description

**What happened?**
The runner E2E cell
`completion-updates.runner-codex.local.handoff-completion-restart` timed
out in setup. The run ledger shows both agents report
`permission_denied` (EPERM) for `node .../wait-for-brief-*.cjs`. The
worker run cwd was `<instance>/isolated-workspaces/<company>/<issue>`.
The fixture wrote the script to the managed project workspace and the
agent home.

**What did you expect to happen?**
The worker waits at the brief gate while the chat is idle. Then the cell
releases the brief, holds the completion reply at its gate, and restarts
the server.

**Steps to reproduce**
`pnpm test:e2e:runner -- --max-automatic-retries 0 --id
completion-updates.runner-codex.local.handoff-completion-restart` on
master `6cafcaf89b`.

**Classification**
Test defect. The failure happens before the restart. Workspace isolation
is the intended product behavior.

## What Changed

- `tests/runner-e2e/chat-stories.ts`: add `workspaceChatBrief(nonce,
timeoutMs)`. It returns a bounded `node -e` command that reads and
writes only cwd-relative files, plus `at(dir)` to find the gate and
ready files in a workspace.
- `tests/runner-e2e/completion-update-flow.ts`: the worker and
completion instructions use that command. The fixture reads readiness
from, and publishes briefs to, `isolated-workspaces/<company>/<issue>`
for each delegated task and the source chat. The setup poll state now
records the worker run cwd. Cleanup releases every wait that is still
open.
- `tests/runner-e2e/chat-stories.test.ts`: regression test. It runs the
command from a temporary cwd, checks that the command names no host
path, and checks the nonce and timeout bounds. It was red before the
helper existed.
- `tests/runner-e2e/catalog.ts`: bump the `completion-updates`
definition to version 28 and set `workerBriefWorkspace:
"run-isolated-task-directory"`.
- `tests/runner-e2e/README.md`: describe the new brief location.

## Verification

- `npx vitest run --config tests/runner-e2e/vitest.config.ts
tests/runner-e2e/chat-stories.test.ts
tests/runner-e2e/completion-updates.test.ts
tests/runner-e2e/catalog.test.ts`: 108 passed.
- Live cell, native Codex `gpt-5.6-sol`, local runner: `pnpm
test:e2e:runner -- --max-automatic-retries 0 --id
completion-updates.runner-codex.local.handoff-completion-restart`.
Results are in the Verification comment below.
- Two earlier local attempts in this worktree failed in setup with
`harness_test_failed`. The worktree did not have a built
`paperclip-runnerd`. After `pnpm --filter @paperclipai/paperclip-runner
build`, the cell passed.

## Risks

- Low risk. The change is in test fixtures only. No product code
changes.
- The idle, busy, and multiple cells share this flow. They now also use
the isolated task directory. That is the same directory the product
selects for these tasks.
- The agent must run the inline command from its cwd. The instructions
say this, and the command fails closed (no gate) if the agent runs it
elsewhere.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits). Default context window. Extended reasoning
on.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

tests/runner-e2e/README.md

@@ -675,8 +675,10 @@ before execution.
 
 The idle chat cell asks the agent to delegate one welcome note to a named worker and
 report its result without another user message. A bounded local file read in
-the managed project workspace delays completion until the source chat is positively
-observed idle, with a three-minute handoff setup budget and a four-minute worker
+the worker task's own isolated task directory delays completion until the source
+chat is positively observed idle. The wait command names only cwd-relative files,
+because native providers cannot read agent homes or unconfigured project roots. The
+setup uses a three-minute handoff setup budget and a four-minute worker
 wait limit. The brief is then released, the worker must save the output and
 reach Done. Its output must include the start time supplied only in that brief, allowing
 ordinary numeric and written forms. That check runs after completion observation

tests/runner-e2e/catalog.ts

@@ -1934,7 +1934,7 @@ export const runnerSuites: readonly RunnerSuiteFixture[] = [
     environments: [localEnvironment],
     tasks: [...firstTaskTasks.filter(task => task.id === "interview-plan-accept"), ...chatCompletionTasks],
     expectedMatrixSize: 10,
-    definitionMetadata: { version: 27, runGrading: "evidenced-nonexecution-and-refusal", resultNavigation: "loaded-task-header", instructionSetup: "read-before-write-base-hash", requirementEvidence: "recorded-user-comments-and-resolved-answers", busyReferenceWait: "committed-conversation-document-response-held", busyBoundary: "source-tool-in-flight-and-public-deferred-wake", workerReference: "rsvp-code-in-saved-note", judge: "completion-quality-v14-observed-rendered-result-access", judgeMaxDollarsPerRequest: 0.5, instructions: "production", correlation: "authoritative-task-facts-required-in-reply-run", restartBoundary: "done-and-source-provider-at-reference-gate", idleBoundaryTimeoutMs: 180_000, workerBriefTimeoutMs: 240_000, workerBriefWorkspace: "managed-project", workerBriefEvidence: "released-start-time", grading: "post-completion-reply-and-result-access", semanticReview: "required-separately", chatBoundary: "worker-gated-until-source-idle", observationWindowMs: 120_000, scheduling: "explicit-only" },
+    definitionMetadata: { version: 28, runGrading: "evidenced-nonexecution-and-refusal", resultNavigation: "loaded-task-header", instructionSetup: "read-before-write-base-hash", requirementEvidence: "recorded-user-comments-and-resolved-answers", busyReferenceWait: "committed-conversation-document-response-held", busyBoundary: "source-tool-in-flight-and-public-deferred-wake", workerReference: "rsvp-code-in-saved-note", judge: "completion-quality-v14-observed-rendered-result-access", judgeMaxDollarsPerRequest: 0.5, instructions: "production", correlation: "authoritative-task-facts-required-in-reply-run", restartBoundary: "done-and-source-provider-at-reference-gate", idleBoundaryTimeoutMs: 180_000, workerBriefTimeoutMs: 240_000, workerBriefWorkspace: "run-isolated-task-directory", workerBriefEvidence: "released-start-time", grading: "post-completion-reply-and-result-access", semanticReview: "required-separately", chatBoundary: "worker-gated-until-source-idle", observationWindowMs: 120_000, scheduling: "explicit-only" },
 
   },
   ...(process.env.PAPERCLIP_RUNNER_E2E_CONNECTION_REVIEWS === "1" ? [connectionReviewSuite] : []),

tests/runner-e2e/chat-stories.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { assertInterruptedChat, prepareChatBrief, publishChatBrief } from "./chat-stories.js";
+import { assertInterruptedChat, prepareChatBrief, publishChatBrief, workspaceChatBrief } from "./chat-stories.js";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -38,6 +38,28 @@ describe("active chat follow-up oracle", () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+  it("waits for a brief inside the agent's own working directory without host paths", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "chat-brief-relative-"));
+    try {
+      const brief = workspaceChatBrief("fixture-1", 5_000);
+      // A sandboxed agent can read only its own workspace. The command must
+      // not name the fixture host directory, and must resolve from its cwd.
+      expect(brief.command).not.toContain(root);
+      expect(brief.command).not.toContain(path.sep + "tmp");
+      const { gate, ready } = brief.at(root);
+      const command = promisify(execFile)("/bin/sh", ["-c", brief.command], { cwd: root, timeout: 5_000 });
+      try {
+        await expect.poll(() => readFile(ready, "utf8").catch(() => "")).toBe("waiting");
+      } finally {
+        await publishChatBrief(gate, "BRIEF relative result");
+        expect((await command).stdout.trim()).toBe("BRIEF relative result");
+      }
+      expect(() => workspaceChatBrief("../escape")).toThrow();
+      expect(() => workspaceChatBrief("ok", 0)).toThrow("bounded");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
   it("accepts either steering or one queued successor, with the saved correction", () => {
     expect(() => assertInterruptedChat(valid)).not.toThrow();
     expect(() => assertInterruptedChat({ ...valid, runs: [run, { ...run, id: "successor" }], comments: [...valid.comments.slice(0, 2), { ...valid.comments[2]!, createdByRunId: "successor" }] })).not.toThrow();

tests/runner-e2e/chat-stories.ts

@@ -79,6 +79,23 @@ export async function prepareChatBrief(workspacePath: string, nonce: string, tim
   return { gate, ready, scriptPath };
 }
 
+/**
+ * A bounded brief wait that resolves only from the agent's working directory.
+ * Sandboxed native providers can read their own task directory but not agent
+ * homes or unrelated project roots, so the command names no host path. The
+ * fixture publishes to `at(<the run's workspace>)` once that directory is known.
+ */
+export function workspaceChatBrief(nonce: string, timeoutMs = 120_000) {
+  if (!/^[A-Za-z0-9_-]+$/.test(nonce)) throw new Error("Brief nonce must be a plain file name segment");
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000) throw new Error("Brief wait must be bounded between 1 and 300000ms");
+  const name = `chat-brief-${nonce}.txt`;
+  const script = `const fs=require("node:fs"),g="${name}",end=Date.now()+${Math.floor(timeoutMs)};fs.writeFileSync(g+".waiting","waiting");const t=setInterval(()=>{if(fs.existsSync(g)){console.log(fs.readFileSync(g,"utf8"));clearInterval(t)}else if(Date.now()>end){clearInterval(t);process.exitCode=1}},100)`;
+  return {
+    command: `node -e '${script}'`,
+    at: (workspacePath: string) => ({ gate: path.join(workspacePath, name), ready: path.join(workspacePath, `${name}.waiting`) }),
+  };
+}
+
 export async function runChatInterruption(context: Context & { refreshIssue(): Promise<void> }) {
   const { input, marker, idle, allRuns, comments } = context;
   // Unprojected host /tmp files are intentionally hidden from native Codex.

tests/runner-e2e/completion-update-flow.ts

@@ -1,11 +1,11 @@
 import { expect, type Page } from "@playwright/test";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { resolveManagedProjectWorkspaceDir, resolveDefaultAgentWorkspaceDir } from "../../server/src/home-paths.js";
+import { resolvePaperclipInstanceRoot } from "../../server/src/home-paths.js";
 import { pollUntil, type RunnerApi } from "./api.js";
 import { sendChatMessage, readChatOutputDocument, collectChatRunEvidence, type ChatFlowInput, type ChatRun } from "./chat-flow.js";
 import { arm as armDocumentGate, clear as clearDocumentGate, release as releaseDocumentGate, waitUntilHeld } from "./context-comment-gate.js";
-import { prepareChatBrief, publishChatBrief } from "./chat-stories.js";
+import { publishChatBrief, workspaceChatBrief } from "./chat-stories.js";
 import { completionDelivery, completionOutputUsesReleasedBrief, type CompletionObservation } from "./completion-updates.js";
 
 type Row = Record<string, any>;
@@ -132,23 +132,35 @@ export async function runChatCompletionUpdate(context: {
   const restart = execution.task.id === "handoff-completion-restart";
   const taskCount = multiple ? 2 : 1;
   const userMessages: string[] = [];
-  const completionWait = restart ? await prepareChatBrief(resolveDefaultAgentWorkspaceDir(f.agent.id), `${input.nonce}-completion`, 240_000) : null;
+  // Native runs see only their own task directory: a chat in its isolated
+  // conversation directory and a task in a workspace-free project in its
+  // isolated task directory. Agent homes and unconfigured project roots are
+  // outside the provider sandbox, so each wait resolves from the run's cwd.
+  const taskDirectory = (issueId: string) => {
+    const directory = path.join(resolvePaperclipInstanceRoot(), "isolated-workspaces", f.company.id, issueId);
+    const relative = path.relative(path.dirname(input.workspacePath), directory);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Completion fixture escaped isolated instance");
+    return directory;
+  };
+  const publishBrief = async (brief: ReturnType<typeof workspaceChatBrief>, issueId: string, content: string) => {
+    const directory = taskDirectory(issueId);
+    await mkdir(directory, { recursive: true });
+    await publishChatBrief(brief.at(directory).gate, content);
+  };
+  const runCwd = (runs: Row[], issueId: string) =>
+    runs.filter(r => r.contextSnapshot?.issueId === issueId).map(r => r.contextSnapshot?.paperclipWorkspace?.cwd ?? null);
+  const completionWait = restart ? workspaceChatBrief(`${input.nonce}-completion`, 240_000) : null;
   if (completionWait) {
-    const instruction = `For automatic delegated-work completion updates, first run node ${completionWait.scriptPath} and read the organizer's reference before posting your final reply. Do not run this script for the initial task handoff or other user messages. Reading this reference does not authorize additional tasks or changes to the completed work.`;
+    const instruction = `For automatic delegated-work completion updates, first run this exact command from your current working directory and read the organizer's reference before posting your final reply:\n\n${completionWait.command}\n\nDo not run this command for the initial task handoff or other user messages. Reading this reference does not authorize additional tasks or changes to the completed work.`;
     await api.saveAgentInstructions(f.agent.id, instruction);
   }
   const config = execution.profile.buildAgent({ environmentId: f.environment.id, environmentFixtureId: "local", workspacePath: input.workspacePath, secretRefs: f.secretRefs, executionId: input.nonce });
   const worker = await api.post<Row>(`${company}/agents`, { ...config, name: "Riley Writer", role: "engineer", reportsTo: f.agent.id });
   const project = await api.post<Row>(`${company}/projects`, { name: "Garden welcome", description: "A non-code neighborhood garden meetup. No repository needed." });
-  // A project task runs in its managed project workspace. The agent-home path
-  // used by projectless chats is outside the native Codex workspace projection.
-  const workspace = resolveManagedProjectWorkspaceDir({ companyId: f.company.id, projectId: project.id });
-  const relative = path.relative(path.dirname(input.workspacePath), workspace);
-  if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Completion fixture escaped isolated instance");
-  const wait = await prepareChatBrief(workspace, input.nonce, 240_000);
+  const wait = workspaceChatBrief(input.nonce, 240_000);
   const reference = marker;
   const brief = `The free Friday meetup starts at 10:30 in the community garden. The saved note must include RSVP code ${reference}.`;
-  const instructions = `For the welcome-note assignment, run node ${wait.scriptPath} to read the organizer's brief before writing the final note. Save a two-sentence welcome note as a Paperclip document on your assigned task using the brief's details and explicitly include its RSVP code in the note. Then complete your task. Do not edit or comment on another task.`;
+  const instructions = `For the welcome-note assignment, run this exact command from your task's working directory to read the organizer's brief before writing the final note:\n\n${wait.command}\n\nSave a two-sentence welcome note as a Paperclip document on your assigned task using the brief's details and explicitly include its RSVP code in the note. Then complete your task. Do not edit or comment on another task.`;
   await api.saveAgentInstructions(worker.id, instructions);
   expect(await api.get(`/api/agents/${worker.id}/instructions-bundle/file?path=AGENTS.md`)).toMatchObject({ content: instructions });
   const prompt = `Create ${multiple ? "two separate tasks titled Welcome note A and Welcome note B" : "one task"} in the Garden welcome project (${project.id}) assigned to Riley Writer to write a two-sentence welcome note for our free Friday garden meetup. Riley has the organizer's brief. Save the finished note on that task and include RSVP code ${marker} in the note so attendees know which code to give the organizer. Please tell me here when the work is finished and give me access to the result. You may start the handoff now; no further approval is needed. Let Riley write the note.`;
@@ -165,7 +177,8 @@ export async function runChatCompletionUpdate(context: {
         delegated = tasks.filter(t => t.assigneeAgentId === worker.id);
         task = delegated[0];
         const runs = await context.allRuns();
-        return { source, tasks, runs, ready: await readFile(wait.ready, "utf8").catch(() => "") };
+        const ready = task ? await readFile(wait.at(taskDirectory(task.id)).ready, "utf8").catch(() => "") : "";
+        return { source, tasks, runs, ready, workerCwds: task ? runCwd(runs, task.id) : [] };
       },
       accept: state => delegated.length === taskCount && state.ready === "waiting" && state.source.conversationState === "waiting" &&
         state.runs.some(r => r.contextSnapshot?.issueId === task!.id && r.status === "running") &&
@@ -190,7 +203,7 @@ export async function runChatCompletionUpdate(context: {
       expect(reference.body).toContain(`REFERENCE${marker}`);
       await input.evidence("completion-busy-document-gate.json", { sourceRun: busyRun, document: reference, responseHeld: true });
     }
-    await publishChatBrief(wait.gate, brief);
+    for (const item of delegated) await publishBrief(wait, item.id, brief);
     await pollUntil({ label: "delegated welcome note completed", deadlineAt: Date.now() + 180_000, intervalMs: 1000,
       load: () => api.get<Row>(`/api/issues/${task!.id}`), accept: t => t.status === "done" });
     if (busyRun) {
@@ -216,7 +229,11 @@ export async function runChatCompletionUpdate(context: {
     }
     if (restart) {
       const reportingRun = await pollUntil({ label: "completion reply is waiting at its reference gate before publication", deadlineAt: Date.now() + 120_000, intervalMs: 1000,
-        load: async () => ({ runs: await context.allRuns(), ready: await readFile(completionWait!.ready, "utf8").catch(() => "") }),
+        load: async () => {
+          const runs = await context.allRuns();
+          return { runs, ready: await readFile(completionWait!.at(taskDirectory(context.issue().id)).ready, "utf8").catch(() => ""),
+            sourceCwds: runCwd(runs, context.issue().id) };
+        },
         accept: state => state.ready === "waiting" && state.runs.some(r => r.contextSnapshot?.issueId === context.issue().id &&
           r.contextSnapshot?.wakeReason === "chat_task_completed" && r.status === "running") });
       const beforeRestart = await api.get<Row[]>(`/api/issues/${context.issue().id}/comments?order=asc`);
@@ -227,7 +244,7 @@ export async function runChatCompletionUpdate(context: {
       // neither task records nor completion events are fabricated by the fixture.
       await input.evidence("completion-restart-boundary.json", { worker: await api.get(`/api/issues/${task!.id}`), runs: reportingRun.runs, sourceReferenceGateReady: true });
       await input.restart();
-      await publishChatBrief(completionWait!.gate, "The organizer is ready to receive the saved result. Report the completed work now.");
+      await publishBrief(completionWait!, context.issue().id, "The organizer is ready to receive the saved result. Report the completed work now.");
       await page.goto(`/${f.company.issuePrefix}/chats/${f.agent.id}`, { waitUntil: "commit" });
     }
     for (const [index, item] of delegated.entries()) {
@@ -253,9 +270,12 @@ export async function runChatCompletionUpdate(context: {
       expect(replies, `one correlated completion reply for ${item.id}`).toHaveLength(1);
     }
   } finally {
-    await publishChatBrief(wait.gate, `Reference: ${reference}`);
+    // Release every wait a failed attempt may have left running.
+    const release = (work: Promise<void>) => work.catch(() => {});
+    for (const item of delegated) await release(publishBrief(wait, item.id, `Reference: ${reference}`));
     if (busy) await releaseDocumentGate(context.issue().id);
-    if (completionWait) await publishChatBrief(completionWait.gate, "The organizer is ready to receive the saved result.");
+    const sourceId = (context.issue() as { id: string } | undefined)?.id;
+    if (completionWait && sourceId) await release(publishBrief(completionWait, sourceId, "The organizer is ready to receive the saved result."));
     await context.refreshIssue();
   }
 }