From 474d7514e1bf8326aadbf49c5361e982670a71f4 Mon Sep 17 00:00:00 2001 From: Pixel Perfect Date: Fri, 20 Nov 2026 13:13:15 -0800 Subject: [PATCH 1/3] fix(issues): a No project thread can read and write its linked Linear issues A standalone tracker signs in with the environment's credential, so any project serves its references: the No project, a project with no binding, or a project bound to another team. Writes follow the tracker's own account permissions. Standalone URLs still have to name the credential's workspace, and another repository on a git host stays read-only. --- apps/server/src/issue/IssueService.test.ts | 43 +++++++--- apps/server/src/issue/IssueService.ts | 92 ++++++++++++++++------ docs/user/source-control.md | 14 +++- 3 files changed, 113 insertions(+), 36 deletions(-) diff --git a/apps/server/src/issue/IssueService.test.ts b/apps/server/src/issue/IssueService.test.ts index 1251729b5bbac..7bf96c73193bb 100644 --- a/apps/server/src/issue/IssueService.test.ts +++ b/apps/server/src/issue/IssueService.test.ts @@ -583,10 +583,13 @@ describe("IssueService with a standalone tracker", () => { expect( yield* service.resolveUrl("https://linear.app/acme/issue/ENG-1/old-title"), ).toMatchObject({ key: "ENG-1", writable: true }); - const refused = yield* service - .resolveUrl("https://linear.app/other-workspace/issue/ENG-1/old-title") - .pipe(Effect.result); - expect(refused).toMatchObject({ + const otherWorkspace = "https://linear.app/other-workspace/issue/ENG-1/old-title"; + // Bound or not, the link must name the workspace the environment's credential reaches. + const unbound = yield* makeService({ + projects: [project({ id: "notes" })], + trackers: [fakeStandaloneTracker()], + }); + const refusal = { _tag: "Failure", failure: { _tag: "IssueOperationError", @@ -594,7 +597,11 @@ describe("IssueService with a standalone tracker", () => { reason: "not-found", detail: "This issue URL does not belong to the connected workspace.", }, - }); + }; + expect(yield* service.resolveUrl(otherWorkspace).pipe(Effect.result)).toMatchObject(refusal); + expect( + yield* unbound.resolveUrl(otherWorkspace, "notes" as ProjectId).pipe(Effect.result), + ).toMatchObject(refusal); }), ); @@ -682,17 +689,33 @@ describe("IssueService with a standalone tracker", () => { }, }); - // Unbound, the standalone scope is gone and its references are unsupported. + // Another team on the bound tracker is reached by the same environment credential. + yield* bound.update({ ...linearRef, scope: "OPS", key: "OPS-1", title: "Renamed" }); + + // Unbound, the standalone scope leaves the listing, but the environment's credential still + // serves references, from a project with no repository (No project) too. listed.length = 0; const unbound = yield* makeService({ projects, trackers }); const after = yield* unbound.list({ state: "open" }); expect(listed).toEqual(["github github.com acme/web"]); expect(after.trackers.map((tracker) => tracker.tracker)).toEqual(["github"]); - const refused = yield* Effect.flip(unbound.detail(linearRef)); - expect(refused).toMatchObject({ - _tag: "IssueUnavailableError", - reason: "tracker-unsupported", + const noProjectRef = { ...linearRef, projectId: "notes" as ProjectId }; + expect(yield* unbound.detail(noProjectRef)).toMatchObject({ + projectId: "notes", + host: "linear.app", + writable: true, }); + yield* unbound.comment({ ...noProjectRef, body: "Follow-up" }); + yield* unbound.setState({ ...noProjectRef, state: "Done" }); + expect( + yield* unbound.resolveUrl( + "https://linear.app/acme/issue/ENG-1/issue-title", + "notes" as ProjectId, + ), + ).toMatchObject({ projectId: "notes", host: "linear.app", key: "ENG-1", writable: true }); + expect( + yield* Effect.flip(unbound.detail({ ...noProjectRef, host: "linear.example" })), + ).toMatchObject({ _tag: "IssueUnavailableError", reason: "tracker-unsupported" }); // A project with no remote at all can still be bound, and then has only the standalone one. const standaloneOnly = yield* makeService({ diff --git a/apps/server/src/issue/IssueService.ts b/apps/server/src/issue/IssueService.ts index 56712954a49cb..7ab8800600fac 100644 --- a/apps/server/src/issue/IssueService.ts +++ b/apps/server/src/issue/IssueService.ts @@ -162,9 +162,10 @@ export class IssueService extends Context.Service< projectId: ProjectId, ) => Effect.Effect; /** - * Resolve through a matching project, preferring `preferredProjectId`; other scopes are read-only. - * Standalone links must match the workspace in the issue's canonical URL from the connected - * tracker; that read comes back as `issue`, so callers need not read it again. + * Resolve through a matching project, preferring `preferredProjectId`; another git-host + * repository is read-only. A standalone link with no project bound to its tracker resolves + * through `preferredProjectId`, and must match the workspace in the issue's canonical URL from + * the connected tracker; that read comes back as `issue`, so callers need not read it again. */ readonly resolveUrl: ( url: string, @@ -288,16 +289,57 @@ const make = Effect.gen(function* () { }), ); + /** + * A standalone tracker signs in with the environment's credential, not a checkout's, so any + * project serves its references, bound or not (No project included). The tracker itself + * decides what the account may change. + */ + const requireStandaloneProject = ( + ref: IssueScopeRef, + api: StandaloneIssueTrackerApi, + ): Effect.Effect => { + const host = ref.host?.trim().toLowerCase(); + if (host !== undefined && host !== api.standalone.host) { + return Effect.fail(new IssueUnavailableError({ reason: "tracker-unsupported" })); + } + return projects.getShell(ref.projectId).pipe( + Effect.mapError( + (cause) => + new IssueOperationError({ + operation: "listProjects", + detail: "The project list could not be read.", + cause, + }), + ), + Effect.flatMap( + Option.match({ + onNone: () => Effect.fail(new IssueUnavailableError({ reason: "tracker-unsupported" })), + onSome: (project) => + Effect.succeed({ + project, + api, + tracker: ref.tracker, + host: api.standalone.host, + scope: ref.scope.trim(), + writable: true, + }), + }), + ), + ); + }; + /** * The project whose checkout and credentials serve a reference, and whether the reference is - * one of the project's own scopes. A reference naming another scope on the same tracker and - * host is served by the project but marked read-only. A project with two trackers serves the - * one the reference names. + * one of the project's own scopes. A reference naming another repository on the same git host + * is served by the project but marked read-only. A project with two trackers serves the one the + * reference names. */ const requireProject = ( ref: IssueScopeRef, - ): Effect.Effect => - listProjects({ projectId: ref.projectId }).pipe( + ): Effect.Effect => { + const api = registry.get(ref.tracker); + if (api !== null && isStandaloneIssueTracker(api)) return requireStandaloneProject(ref, api); + return listProjects({ projectId: ref.projectId }).pipe( Effect.flatMap(({ supported }) => { const host = ref.host?.trim().toLowerCase(); const onHost = supported.filter( @@ -315,6 +357,7 @@ const make = Effect.gen(function* () { return Effect.succeed({ ...served, scope, writable: own !== undefined }); }), ); + }; const requireWritable = (ref: IssueScopeRef, operation: string) => requireProject(ref).pipe( @@ -730,28 +773,33 @@ const make = Effect.gen(function* () { onTracker.filter((project) => project.scope.toLowerCase() === gitHost?.link.scopeAlias), ); const lender = own ?? preferFirst(onTracker); - if (lender === undefined) { - return yield* new IssueUnavailableError({ reason: "tracker-unsupported" }); - } - const served = { - ...lender, - scope: own === undefined ? link.scope : lender.scope, - writable: own !== undefined, - }; + const served = + lender !== undefined + ? { + ...lender, + scope: own === undefined ? link.scope : lender.scope, + writable: standalone !== null || own !== undefined, + } + : standalone !== null && preferredProjectId !== undefined + ? yield* requireStandaloneProject( + { projectId: preferredProjectId, tracker, scope: link.scope }, + standalone.api, + ) + : yield* new IssueUnavailableError({ reason: "tracker-unsupported" }); const resolved = { - projectId: lender.project.id, - tracker: lender.tracker, - host: lender.host, + projectId: served.project.id, + tracker: served.tracker, + host: served.host, scope: served.scope, key: link.key, writable: served.writable, }; if (standalone === null) return resolved; // Team keys repeat across workspaces; only the credential's canonical issue URL identifies one. - const issue = yield* lender.api + const issue = yield* served.api .getIssue({ - cwd: lender.project.workspaceRoot, - host: lender.host, + cwd: served.project.workspaceRoot, + host: served.host, scope: link.scope, key: link.key, }) diff --git a/docs/user/source-control.md b/docs/user/source-control.md index 1bd54659eb5af..033ba1ffc5c9f 100644 --- a/docs/user/source-control.md +++ b/docs/user/source-control.md @@ -376,7 +376,11 @@ The **Views** menu saves and restores a search, filter, and sort setup, as it do requests. To list a Linear team's issues beside a project's, connect Linear with an API key under -Settings → Source control & issues, then choose the team for that project there. +Settings → Source control & issues, then choose the team for that project there. The team sets +what the Issues page lists for the project, and where agents in its threads look up an issue by its +key alone or file a new one. An issue linked by its full URL needs no team: once Linear is +connected, a Linear issue linked to any thread, No project threads included, opens and can be +changed as far as your Linear account allows. Select an issue to open it beside the list: description, comments, state changes, linked pull requests, labels, assignees, and reactions. Linked pull requests open in the same panel. You can @@ -386,9 +390,11 @@ allow it. An issue read through a project that does not own its repository is sh An issue can be kept with a thread the way a pull request can: open it beside the thread (issue links in the conversation open there) and use **Link to this thread** in its header; **Unlink** -undoes it. Click the issue badge in the thread sidebar to see its issues and pull requests in -**Linked items**. Select an issue there to open it beside the thread. Agents link the issues they -work on with the `link_issue` tool. +undoes it. A Linear link in the conversation opens beside the thread only when a project in the +environment is bound to a Linear team; otherwise it opens in the browser. Click the issue badge in +the thread sidebar to see its issues and pull requests in **Linked items**. Select an issue there +to open it beside the thread. Agents link the issues they work on with the `link_issue` tool, which +takes any Linear issue's URL once Linear is connected, bound or not. Writing to a tracker over a remote connection requires the `source-control:write` scope. From d5e4b6976e8c8ae4353275ccd662c883480b8648 Mon Sep 17 00:00:00 2001 From: Pixel Perfect Date: Fri, 20 Nov 2026 15:11:20 -0800 Subject: [PATCH 2/3] fix(issues): keep bound Linear projects as they are on main Only a project with no binding for the tracker, the No project included, serves its references with the environment's credential. A project bound to a Linear team keeps main's behavior: another team's issues stay read-only, and URL resolution goes through the bound project as before. --- apps/server/src/issue/IssueService.test.ts | 9 +++-- apps/server/src/issue/IssueService.ts | 38 +++++++++++----------- docs/user/source-control.md | 4 +-- 3 files changed, 28 insertions(+), 23 deletions(-) diff --git a/apps/server/src/issue/IssueService.test.ts b/apps/server/src/issue/IssueService.test.ts index 7bf96c73193bb..6df52796b553c 100644 --- a/apps/server/src/issue/IssueService.test.ts +++ b/apps/server/src/issue/IssueService.test.ts @@ -689,8 +689,13 @@ describe("IssueService with a standalone tracker", () => { }, }); - // Another team on the bound tracker is reached by the same environment credential. - yield* bound.update({ ...linearRef, scope: "OPS", key: "OPS-1", title: "Renamed" }); + // Another team on the bound tracker is served by the project, read-only. + const otherTeam = { ...linearRef, scope: "OPS", key: "OPS-1" }; + expect(yield* bound.detail(otherTeam)).toMatchObject({ scope: "OPS", writable: false }); + expect(yield* Effect.flip(bound.update({ ...otherTeam, title: "Renamed" }))).toMatchObject({ + _tag: "IssueOperationError", + reason: "read-only", + }); // Unbound, the standalone scope leaves the listing, but the environment's credential still // serves references, from a project with no repository (No project) too. diff --git a/apps/server/src/issue/IssueService.ts b/apps/server/src/issue/IssueService.ts index 7ab8800600fac..74e5399a56682 100644 --- a/apps/server/src/issue/IssueService.ts +++ b/apps/server/src/issue/IssueService.ts @@ -162,10 +162,10 @@ export class IssueService extends Context.Service< projectId: ProjectId, ) => Effect.Effect; /** - * Resolve through a matching project, preferring `preferredProjectId`; another git-host - * repository is read-only. A standalone link with no project bound to its tracker resolves - * through `preferredProjectId`, and must match the workspace in the issue's canonical URL from - * the connected tracker; that read comes back as `issue`, so callers need not read it again. + * Resolve through a matching project, preferring `preferredProjectId`; other scopes are read-only. + * A standalone link with no project bound to its tracker resolves through `preferredProjectId`, + * and must match the workspace in the issue's canonical URL from the connected tracker; that + * read comes back as `issue`, so callers need not read it again. */ readonly resolveUrl: ( url: string, @@ -290,9 +290,8 @@ const make = Effect.gen(function* () { ); /** - * A standalone tracker signs in with the environment's credential, not a checkout's, so any - * project serves its references, bound or not (No project included). The tracker itself - * decides what the account may change. + * A project with no binding for a standalone tracker, the No project included, serves its + * references with the environment's credential. The tracker decides what the account may change. */ const requireStandaloneProject = ( ref: IssueScopeRef, @@ -330,21 +329,23 @@ const make = Effect.gen(function* () { /** * The project whose checkout and credentials serve a reference, and whether the reference is - * one of the project's own scopes. A reference naming another repository on the same git host - * is served by the project but marked read-only. A project with two trackers serves the one the - * reference names. + * one of the project's own scopes. A reference naming another scope on the same tracker and + * host is served by the project but marked read-only. A project with two trackers serves the + * one the reference names, and one with no binding for a standalone tracker still serves it. */ const requireProject = ( ref: IssueScopeRef, - ): Effect.Effect => { - const api = registry.get(ref.tracker); - if (api !== null && isStandaloneIssueTracker(api)) return requireStandaloneProject(ref, api); - return listProjects({ projectId: ref.projectId }).pipe( + ): Effect.Effect => + listProjects({ projectId: ref.projectId }).pipe( Effect.flatMap(({ supported }) => { const host = ref.host?.trim().toLowerCase(); - const onHost = supported.filter( - (candidate) => - candidate.tracker === ref.tracker && (host === undefined || candidate.host === host), + const onTracker = supported.filter((candidate) => candidate.tracker === ref.tracker); + const api = registry.get(ref.tracker); + if (onTracker.length === 0 && api !== null && isStandaloneIssueTracker(api)) { + return requireStandaloneProject(ref, api); + } + const onHost = onTracker.filter( + (candidate) => host === undefined || candidate.host === host, ); const scope = ref.scope.trim(); const own = onHost.find( @@ -357,7 +358,6 @@ const make = Effect.gen(function* () { return Effect.succeed({ ...served, scope, writable: own !== undefined }); }), ); - }; const requireWritable = (ref: IssueScopeRef, operation: string) => requireProject(ref).pipe( @@ -778,7 +778,7 @@ const make = Effect.gen(function* () { ? { ...lender, scope: own === undefined ? link.scope : lender.scope, - writable: standalone !== null || own !== undefined, + writable: own !== undefined, } : standalone !== null && preferredProjectId !== undefined ? yield* requireStandaloneProject( diff --git a/docs/user/source-control.md b/docs/user/source-control.md index 033ba1ffc5c9f..f9600777734a4 100644 --- a/docs/user/source-control.md +++ b/docs/user/source-control.md @@ -379,8 +379,8 @@ To list a Linear team's issues beside a project's, connect Linear with an API ke Settings → Source control & issues, then choose the team for that project there. The team sets what the Issues page lists for the project, and where agents in its threads look up an issue by its key alone or file a new one. An issue linked by its full URL needs no team: once Linear is -connected, a Linear issue linked to any thread, No project threads included, opens and can be -changed as far as your Linear account allows. +connected, a Linear issue linked to any thread, No project threads included, opens beside it. +While no project has a team, you can also change it as far as your Linear account allows. Select an issue to open it beside the list: description, comments, state changes, linked pull requests, labels, assignees, and reactions. Linked pull requests open in the same panel. You can From d66fc146d26981d0a9cb6cb2a910ec20db4d8b39 Mon Sep 17 00:00:00 2001 From: Pixel Perfect Date: Fri, 20 Nov 2026 15:20:44 -0800 Subject: [PATCH 3/3] docs(issues): limit Linear URL linking to the connected workspace --- docs/user/source-control.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user/source-control.md b/docs/user/source-control.md index f9600777734a4..1eb0fd474468f 100644 --- a/docs/user/source-control.md +++ b/docs/user/source-control.md @@ -379,7 +379,8 @@ To list a Linear team's issues beside a project's, connect Linear with an API ke Settings → Source control & issues, then choose the team for that project there. The team sets what the Issues page lists for the project, and where agents in its threads look up an issue by its key alone or file a new one. An issue linked by its full URL needs no team: once Linear is -connected, a Linear issue linked to any thread, No project threads included, opens beside it. +connected, an issue from that Linear workspace linked to any thread, No project threads included, +opens beside it. While no project has a team, you can also change it as far as your Linear account allows. Select an issue to open it beside the list: description, comments, state changes, linked pull @@ -394,7 +395,8 @@ undoes it. A Linear link in the conversation opens beside the thread only when a environment is bound to a Linear team; otherwise it opens in the browser. Click the issue badge in the thread sidebar to see its issues and pull requests in **Linked items**. Select an issue there to open it beside the thread. Agents link the issues they work on with the `link_issue` tool, which -takes any Linear issue's URL once Linear is connected, bound or not. +takes the URL of any issue in the connected Linear workspace, bound or not. A URL from another Linear +workspace is refused. Writing to a tracker over a remote connection requires the `source-control:write` scope.