Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(agents): identify Cursor Cloud users without gh permissions (#17168)

Nikita Kabardina6aeb015406f
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index aeb4c6e88e..afc5520edc 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -9,13 +9,15 @@ This repo serves two different people, and they get different halves of it.
Work out which before anything else, and never guess silently.
It is a configuration question, not an interview. Read
-`~/.config/langfuse/me.md`; if it is not there, `gh api repos/langfuse/langfuse
---jq .permissions` settles contributor versus maintainer on its own, and for
-anything it cannot tell you β€” which areas they work on β€” **just ask, once**, and
-write the answer to that file so nobody asks again. That is a question and a
-file, not a process. Someone who has worked here for a year does not need
-onboarding; they need you to know their name. `langfuse-onboarding` is for
-people who are actually new.
+`~/.config/langfuse/me.md`; if it is not there, `langfuse-onboarding` step 1
+names them. On Cursor Cloud that is the run owner (`cursor-cloud` `run-info`)
+plus the team roster β€” **not** `gh api …permissions`, because Cloud's GitHub
+token is a read-only integration and reports `push: false` for maintainers.
+Desktop still uses `gh api user` then `.permissions.push`. For anything those
+cannot tell you β€” which areas they work on β€” **just ask, once**, and write the
+answer to that file so nobody asks again. Someone who has worked here for a
+year does not need onboarding; they need you to know their name.
+`langfuse-onboarding` is for people who are actually new.
**An outside contributor** gets the code and `CONTRIBUTING.md`: how to build it,
what the checks require, how to open a pull request. Nothing about the tracker,
@@ -57,8 +59,8 @@ than two sentences they read.
- Know who you are working for before you assume what they may do. An outside
contributor and a Langfuse maintainer get different halves of this repo, and
the difference is derivable β€” `~/.config/langfuse/me.md` if it exists, else
- `gh api repos/langfuse/langfuse --jq .permissions`. `langfuse-onboarding`
- establishes it once and records it; never guess it silently.
+ `langfuse-onboarding` step 1 (Cloud run owner, not Cloud `gh` permissions).
+ Never guess it silently.
- Read the minimal local context required for the task.
- Keep changes scoped and avoid unrelated refactors.
- Delegate exploratory or noisy work β€” broad code search, multi-file
@@ -198,6 +200,15 @@ langfuse/
### Cursor Cloud specific instructions
+- Identity: `cursor-cloud` `run-info` (`owningUserName`, `owningUserEmail`),
+ then the roster. Repo postinstall and Cloud start normally recover
+ `~/.config/langfuse/me.md` from `LINEAR_API_KEY` first. Ignore `git config`
+ (`[email protected]`) and Cloud `gh` `.permissions.push`.
+- Linear: MCP if already authorized; else a real read with `LINEAR_API_KEY`
+ (or `LINEAR_TOKEN` / `LINEAR_API_TOKEN`). Interactive `mcp_auth` does not
+ work in Cloud. If neither works, tell them to add **`LINEAR_API_KEY`** as a
+ Cursor Cloud secret (https://cursor.com/dashboard/cloud-agents) and start a
+ new run β€” this one cannot see a secret added later.
- Cursor Cloud starts the complete source-built stack through
`scripts/agents/start-cursor-cloud.sh`; do not start a second web or worker
process on ports 3000 or 3030.
diff --git a/.agents/README.md b/.agents/README.md
index e77663825c..f4153a93ab 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -232,6 +232,13 @@ idempotent setup and then installs Cursor's Playwright system dependencies.
Each agent run starts the six-service source stack with
`scripts/agents/start-cursor-cloud.sh`.
+Identity recovery runs in both repo postinstall and Cursor Cloud start. When
+`LINEAR_API_KEY` is available, it verifies the viewer belongs to the Langfuse
+team and creates `~/.config/langfuse/me.md` without exposing the key. The file
+is never overwritten, so human corrections survive repeated installs and
+worktrees. Running it at Cloud start matters because environment builds do not
+rerun install for each new agent.
+
The start script builds and waits for web, worker, PostgreSQL, ClickHouse,
Redis, and MinIO, seeds the synthetic demo project, and verifies the web and
worker health endpoints. The default Cursor VM is accepted only after three
@@ -262,7 +269,7 @@ Use HTTP/OAuth where available so credentials remain outside the agent VM.
| --- | --- | --- |
| GitHub | Cursor GitHub App | Enabled for same-repo branches, draft PRs, CI, and preview status |
| Langfuse Docs | Shared HTTP MCP | Enabled, read-only |
-| Linear | Shared OAuth MCP | Enabled; allow read/search tools only |
+| Linear | Shared OAuth MCP | Enabled; allow read/search tools only. Cursor Cloud cannot complete that OAuth prompt β€” maintainers add a personal `LINEAR_API_KEY` secret at https://cursor.com/dashboard/cloud-agents and start a new run. |
| Datadog EU and US | Team Marketplace MCPs | Enabled; allow logs, metrics, traces, dashboards, and monitor reads only |
| Metabase | Team Marketplace MCP | Enabled; allow metadata and query reads only |
| Pylon | Team Marketplace MCP | Enabled; allow issue/thread/customer reads only |
diff --git a/.agents/skills/cursor-agents-workflow/SKILL.md b/.agents/skills/cursor-agents-workflow/SKILL.md
index 2f7759f8fb..6d53fe67b2 100644
--- a/.agents/skills/cursor-agents-workflow/SKILL.md
+++ b/.agents/skills/cursor-agents-workflow/SKILL.md
@@ -34,17 +34,20 @@ Wrong: `cursor/short-descriptive-title-8c78`
## Linear connection
-Cursor can reach Linear β€” desktop and cloud β€” but the MCP server is not
-configured by default, so it is a one-time setup step per developer. Langfuse
-engineers: the write policy is
-[`linear-agent-writes`](../linear-agent-writes/SKILL.md). Configure the connection
-once; agents are expected to read a ticket's history before starting and to leave
-their context on it when they finish.
-
-If Linear is not reachable in your environment, **say so in your handoff
-message** and hand back the context that should have gone on the ticket. Do not
-skip it silently β€” a missing connection that nobody notices looks exactly like a
-practice being followed.
+Cursor desktop can authorize the Linear MCP interactively. Cursor Cloud cannot:
+`mcp_auth` is desktop-only, and the Cloud GitHub token is unrelated to Linear.
+
+On Cloud, prove Linear with a real read. If the MCP is `needsAuth` or missing,
+use `LINEAR_API_KEY` (or `LINEAR_TOKEN` / `LINEAR_API_TOKEN`) via GraphQL or
+`lf-context.sh`. If that env is unset, **say so** and tell them to add
+**`LINEAR_API_KEY`** at https://cursor.com/dashboard/cloud-agents, then start a
+new run. Langfuse engineers: the write policy is
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md). Identity is
+[`langfuse-onboarding`](../langfuse-onboarding/SKILL.md) β€” Cloud `run-info`, not
+Cloud `gh` permissions.
+
+If Linear is not reachable, **say so in your handoff message** and hand back
+the context that should have gone on the ticket. Do not skip it silently.
## Pull requests
diff --git a/.agents/skills/langfuse-onboarding/SKILL.md b/.agents/skills/langfuse-onboarding/SKILL.md
index 7af212cdff..ed8b966922 100644
--- a/.agents/skills/langfuse-onboarding/SKILL.md
+++ b/.agents/skills/langfuse-onboarding/SKILL.md
@@ -2,11 +2,12 @@
name: langfuse-onboarding
description: |
Configure an agent for whoever is using it β€” outside contributor or Langfuse
- maintainer, which areas they work on, which integrations are connected β€” and,
- for someone genuinely new, walk them through onboarding. Use on "onboard me",
- "I'm new here", "what do I need to set up", "am I set up correctly", "why
- can't you see my tickets", and whenever you need to know someone's role and
- no identity file exists yet.
+ maintainer, which areas they work on, and whether Linear answers. On Cursor
+ Cloud, identify the run owner (not Cloud gh permissions) and treat missing
+ Linear as a LINEAR_API_KEY secret to set. Use on "onboard me", "I'm new here",
+ "what do I need to set up", "am I set up correctly", "why can't you see my
+ tickets", "what should I do today" when me.md is missing, and whenever you
+ need someone's role and no identity file exists yet.
---
# Onboarding at Langfuse
@@ -23,29 +24,72 @@ Two jobs, and they are separable β€” most of the time you only want the first.
Everything an agent needs in order to behave differently for a contributor than
for a maintainer comes from the first, so do that before anything else.
-## Step 1 β€” derive the role; do not ask what you can find out
+## Step 1 β€” name them, then prove Linear; do not ask what you can find out
-Two signals, in order. Both are read-only.
+Normal path: `scripts/agents/configure-langfuse-identity.sh` already ran from
+repo postinstall or Cursor Cloud start and created
+`~/.config/langfuse/me.md` from the Linear viewer. Read it and continue. It
+never overwrites an existing file, so the human's Focus and corrections survive
+across worktrees.
+
+Run the local probe first, then stop at the first path that names a person:
```bash
-gh api repos/langfuse/langfuse --jq '.permissions | {push, maintain, admin}'
+bash .agents/skills/langfuse-onboarding/scripts/whoami.sh
```
-- **`push: true`** β†’ maintainer. They have write access to the app repo.
-- **`push: false`** or the call fails β†’ treat as an outside contributor until they
- say otherwise.
-- Then check whether the tracker answers a real read. That is the second signal,
- and the one that matters here: a maintainer with no tracker connection is a
- *setup gap*, not a contributor, and step 4 is where you fix it.
-
-**Do not infer this from `git config user.email`.** That is a local setting, not
-an identity: roughly a third of recent commits here come from personal addresses,
-and both `@clickhouse.com` (the company domain β€” Langfuse is part of ClickHouse)
-and the older `@langfuse.com` are still in daily use. Write access answers the
-question directly, so ask that instead of guessing from a string.
-
-Say what you found and let them correct it. Never announce a role silently β€” a
-wrong guess sends someone down the wrong half of this file.
+It reports whether `me.md` exists, whether a Linear token is in the environment
+(boolean only β€” it never prints the secret), a `linear_viewer` line if that
+token works, and whether `gh api user` works. On Cursor Cloud, a working
+`linear_viewer` is tracker identity even when Linear MCP is `needsAuth`.
+
+**Who, in this order:**
+
+1. **`~/.config/langfuse/me.md`** β€” already recorded. Skip to Linear.
+2. **Cursor Cloud run owner.** If `cursor-cloud` tools exist, call `run-info`.
+ Use `owningUserName` and `owningUserEmail`. Join the name to the roster
+ (`components-mdx/team-members.mdx` in a docs checkout, or
+ `gh api repos/langfuse/langfuse-docs/contents/components-mdx/team-members.mdx`).
+ **Maintainer needs Langfuse-team evidence**: a roster row, or membership of
+ the `LF` team on the Linear read below. Take the GitHub handle from the
+ roster. An `@clickhouse.com` / `@langfuse.com` address alone is *not* that
+ evidence β€” ClickHouse is far larger than this team, and a colleague from
+ another team owns none of the Langfuse tracker. Say the address named them,
+ that you found no Langfuse-team row, and ask once rather than assuming.
+3. **`gh api user` succeeded** (desktop and similar). Then
+ `gh api repos/langfuse/langfuse --jq '.permissions | {push, maintain, admin}'`.
+ **`push: true`** β†’ maintainer. **`push: false`** β†’ contributor until they
+ say otherwise.
+4. If none of the above named them, **ask once**.
+
+**Do not treat Cursor Cloud `gh` as the person.** That token is a read-only
+integration: `gh api user` is 403 and `.permissions.push` is false even for
+maintainers. **Do not infer identity from `git config user.email`** β€” on Cloud
+it is `[email protected]`, and elsewhere it is often a personal address.
+Langfuse is part of ClickHouse; `@clickhouse.com` and `@langfuse.com` are both
+in daily use.
+
+**Linear, in the same step** β€” a maintainer with no tracker is a *setup gap*,
+not a contributor. Prove access with a real read, not a status indicator:
+
+1. Linear MCP tools exist and the namespace is not `needsAuth` β†’ query `viewer`
+ (or list issues).
+2. Else if `whoami.sh` reported a Linear token β†’ GraphQL
+ `{ viewer { name email } teams { nodes { name key } } }` with that env var
+ (never echo it), or `linear-context-handover/scripts/lf-context.sh`. Record
+ the viewer as tracker identity, and treat the `LF` team in that response as
+ the Langfuse-team evidence step 1 asked for. Cloud often has the secret while
+ Linear MCP still shows `needsAuth` β€” the token is the access; do not wait on
+ OAuth.
+3. Else: no Linear. On Cursor Cloud, **do not call `mcp_auth`** β€” it only works
+ in the desktop IDE. Tell them, in one line, to create a personal Linear API
+ key (Linear β†’ Settings β†’ Account β†’ Security) and add it as secret
+ **`LINEAR_API_KEY`** at https://cursor.com/dashboard/cloud-agents, then start
+ a **new** Cloud run. This run cannot see a secret added later. On desktop,
+ authorizing the Linear MCP is enough; `LINEAR_API_KEY` is the headless
+ fallback.
+
+Say what you found and let them correct it. Never announce a role silently.
## Step 2 β€” record it, so this happens once
@@ -58,7 +102,7 @@ cannot live in one repo. Create the directory if it does not exist.
- **Name:** <name>
- **Role:** maintainer | contributor
-- **GitHub:** <login> # from `gh api user --jq .login`
+- **GitHub:** <login> # roster handle on Cloud; `gh api user` on desktop
- **Tracker identity:** <name / email as Linear knows it, or "none">
- **Focus:** <the areas they own or are learning β€” their own words>
- **Checkouts:** <path to langfuse> Β· <path to langfuse-docs> Β· <others>
@@ -146,7 +190,7 @@ and say which ones are missing rather than discovering it mid-task.
| Connect | Needed by |
| --- | --- |
-| **Linear** | 17 skills β€” the tracker practice in all of it |
+| **Linear** | 17 skills β€” the tracker practice in all of it. MCP, or `LINEAR_API_KEY` on headless/Cloud (step 1). |
| **Datadog** | `debug-issue-with-datadog`, `datadog-query-recipes`, `incident-alert-tickets`, `weekly-production-review`, `infra-scaling`, `linear-bug-triage` |
| **AWS** (SSO) | preview seeding and `kubectl` in `langfuse-previews`, plus `infra-scaling`, `security-review` |
| **incident.io** | `incident-alert-tickets`, `weekly-production-review`, `debug-issue-with-datadog` |
@@ -198,4 +242,6 @@ Record the paths you found in `me.md` so the next session does not search again.
It does not decide what to work on β€” that is
[`linear-work-rhythm`](../linear-work-rhythm/SKILL.md), which reads `me.md` and
answers from the tracker. If someone asks "what should I do today" and no
-identity file exists, run step 1 and 2 first, then hand over.
+identity file exists, run step 1 and 2 first. If Linear still does not answer,
+stop and ask them to set `LINEAR_API_KEY` (Cloud) or authorize the Linear MCP
+(desktop) β€” do not invent a day's work.
diff --git a/.agents/skills/langfuse-onboarding/agents/openai.yaml b/.agents/skills/langfuse-onboarding/agents/openai.yaml
index 3b39d7dfa6..e937d2988b 100644
--- a/.agents/skills/langfuse-onboarding/agents/openai.yaml
+++ b/.agents/skills/langfuse-onboarding/agents/openai.yaml
@@ -1,4 +1,4 @@
interface:
display_name: "Langfuse Onboarding"
- short_description: "Establish who you are, then walk the onboarding path"
- default_prompt: "Use $langfuse-onboarding to work out whether I am a contributor or a maintainer, record it, and walk me through setup."
+ short_description: "Name you, then check Linear, including Cursor Cloud"
+ default_prompt: "Use $langfuse-onboarding to work out who I am (Cloud run owner, not Cloud gh permissions), whether Linear answers, and if not tell me to set LINEAR_API_KEY."
diff --git a/.agents/skills/langfuse-onboarding/scripts/whoami.sh b/.agents/skills/langfuse-onboarding/scripts/whoami.sh
new file mode 100755
index 0000000000..c01d00fa2b
--- /dev/null
+++ b/.agents/skills/langfuse-onboarding/scripts/whoami.sh
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Probe identity signals for langfuse-onboarding. Never prints secret values.
+set -euo pipefail
+
+me="${HOME}/.config/langfuse/me.md"
+if [[ -f "${me}" ]]; then
+ echo "me.md: present (${me})"
+else
+ echo "me.md: absent"
+fi
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+
+# Every signal below is independent, so no probe may abort the others: a
+# blocked Linear route must not hide the GitHub lines, and vice versa.
+set +e
+bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" --probe
+linear_probe_status=$?
+set -e
+if [[ "${linear_probe_status}" -ne 0 ]]; then
+ echo "linear_viewer: unavailable (probe exited ${linear_probe_status})"
+fi
+
+set +e
+gh_login="$(gh api user --jq .login 2>/dev/null)"
+gh_user_status=$?
+gh_name=""
+gh_email=""
+if [[ "${gh_user_status}" -eq 0 && -n "${gh_login}" ]]; then
+ gh_name="$(gh api user --jq '.name // ""' 2>/dev/null)"
+ gh_email="$(gh api user --jq '.email // ""' 2>/dev/null)"
+fi
+set -e
+if [[ "${gh_user_status}" -eq 0 && -n "${gh_login}" ]]; then
+ echo "gh_user: ${gh_login} ${gh_name} ${gh_email}"
+ set +e
+ gh_perm_json="$(gh api repos/langfuse/langfuse --jq .permissions 2>/dev/null)"
+ gh_perm_status=$?
+ set -e
+ if [[ "${gh_perm_status}" -eq 0 && -n "${gh_perm_json}" ]]; then
+ python3 -c '
+import json, sys
+p = json.loads(sys.argv[1])
+print("gh_permissions: push=%s maintain=%s admin=%s" % (p.get("push"), p.get("maintain"), p.get("admin")))
+' "${gh_perm_json}" || echo "gh_permissions: unavailable"
+ else
+ echo "gh_permissions: unavailable"
+ fi
+else
+ echo "gh_user: unavailable (Cloud integration tokens 403 here; do not treat as contributor)"
+fi
diff --git a/.agents/skills/linear-agent-writes/SKILL.md b/.agents/skills/linear-agent-writes/SKILL.md
index d368cf4fa6..b44c1d0e76 100644
--- a/.agents/skills/linear-agent-writes/SKILL.md
+++ b/.agents/skills/linear-agent-writes/SKILL.md
@@ -122,12 +122,19 @@ server, and `scripts/agents/sync-agent-shims.mjs` projects it into each tool's
config on `pnpm install`. Those generated files are gitignored build artifacts β€”
never hand-edit them.
-What is left per developer is **authorizing** it, which the first connection
-prompts for. On a headless surface there is nobody to approve that prompt, and a
-remote MCP can report itself connected before any token exists β€” so prove access
-with a real read rather than trusting an indicator, and use a token in an
-`Authorization` header there instead of the interactive flow. Do not commit that
-header: an unset variable is passed through literally and fails with no fallback.
+What is left per developer is **authorizing** it. On desktop, the first
+connection prompts for OAuth. On a headless surface (Cursor Cloud) there is
+nobody to approve that prompt, and `mcp_auth` is not available β€” do not try it.
+
+**Cursor Cloud:** prove Linear with a real read. If the MCP namespace is
+`needsAuth` or empty, look for `LINEAR_API_KEY` (aliases `LINEAR_TOKEN`,
+`LINEAR_API_TOKEN`) and query GraphQL `{ viewer { name email } }` or run
+`linear-context-handover/scripts/lf-context.sh`. Never print the secret. If
+the token is unset, tell them to add **`LINEAR_API_KEY`** at
+https://cursor.com/dashboard/cloud-agents (personal key from Linear β†’ Settings
+β†’ Account β†’ Security) and start a **new** Cloud run. Do not commit that header
+or key; an unset `${LINEAR_API_KEY}` passed through an MCP `headers` block
+fails with no fallback, which is why it is not in `.agents/config.json`.
## When there is no Linear connection: say so, loudly
@@ -138,6 +145,8 @@ is how a practice quietly dies.
Say, in your reply, in plain language:
- that this environment has no Linear access;
+- on Cursor Cloud, that they should set secret **`LINEAR_API_KEY`** and start a
+ new run (interactive Linear OAuth does not work here);
- which step you could not complete (history reconstruction, the handover, the
subtickets);
- and then **the content itself**, ready to paste β€” the handover block, the
diff --git a/.agents/skills/linear-work-rhythm/SKILL.md b/.agents/skills/linear-work-rhythm/SKILL.md
index 80b379ec8f..d2bd83a2c4 100644
--- a/.agents/skills/linear-work-rhythm/SKILL.md
+++ b/.agents/skills/linear-work-rhythm/SKILL.md
@@ -19,10 +19,15 @@ change daily, and a plausible answer assembled from memory is worse than no
answer because nobody can tell it is stale.
Who the person is comes from `~/.config/langfuse/me.md`. If it is not there,
-**ask** β€” their name and what they work on, in one question β€” and write the file
-so it is answered for good. Do not send a colleague of a year through onboarding
-to find out their name; that skill is for people who are new. Do not guess, and
-do not answer this question for an outside contributor, who owns none of it.
+run [`langfuse-onboarding`](../langfuse-onboarding/SKILL.md) step 1 β€” on Cursor
+Cloud that is `run-info` plus the roster, **not** Cloud `gh` permissions, and
+not a "what's your name" interview. Do not guess, and do not answer this
+question for an outside contributor, who owns none of it.
+
+If Linear MCP is `needsAuth` and no `LINEAR_API_KEY` (or `LINEAR_TOKEN` /
+`LINEAR_API_TOKEN`) is set, **stop**. Tell them to add `LINEAR_API_KEY` as a
+Cursor Cloud secret (or authorize Linear MCP on desktop) and start a new run.
+Do not invent a day's work without the tracker.
**The rules behind every check below are the working agreement**, published in
`content/handbook/tools-and-processes/using-linear.mdx` in
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 91d91e7c95..49f183ac87 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -129,8 +129,8 @@ We built a monorepo using [pnpm](https://pnpm.io/motivation) and [turbo](https:/
Requirements
-- Node.js 24 as specified in the [.nvmrc](.nvmrc)
-- pnpm 12.3.1 as specified in `package.json`
+- Node.js 24 as specified in the [.nvmrc](.nvmrc)
+- pnpm 12.3.1 as specified in `package.json`
- Docker to run the database locally
- Clickhouse client
@@ -191,7 +191,9 @@ The start command waits for web, worker, PostgreSQL, ClickHouse, Redis, and
MinIO, then seeds the synthetic demo project and checks both application health
endpoints. Cursor team administrators separately configure the read-only MCP
catalog described in `.agents/README.md`; credentials and OAuth grants belong
-in Cursor, never in repository files.
+in Cursor, never in repository files. Maintainers who need the issue tracker
+inside Cloud should also set secret `LINEAR_API_KEY` (personal Linear API key)
+in the Cloud Agents dashboard; Linear MCP OAuth does not complete in Cloud.
After local verification, a Cursor agent should open a same-repo reviewable
PR (not a draft), apply the GitHub `cursor` label, and test its
diff --git a/scripts/agents/configure-langfuse-identity.sh b/scripts/agents/configure-langfuse-identity.sh
new file mode 100755
index 0000000000..02e11c0105
--- /dev/null
+++ b/scripts/agents/configure-langfuse-identity.sh
@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+identity_dir="${LANGFUSE_CONFIG_DIR:-$HOME/.config/langfuse}"
+identity_file="$identity_dir/me.md"
+mode="${1:-write}"
+
+if [[ "$mode" != "write" && "$mode" != "--probe" ]]; then
+ echo "Usage: $0 [--probe]" >&2
+ exit 2
+fi
+
+if [[ -f "$identity_file" && "$mode" = "write" ]]; then
+ echo "Langfuse identity: already configured at $identity_file"
+ exit 0
+fi
+
+linear_token=""
+linear_token_name=""
+for candidate in LINEAR_API_KEY LINEAR_TOKEN LINEAR_API_TOKEN; do
+ if [[ -n "${!candidate:-}" ]]; then
+ linear_token="${!candidate}"
+ linear_token_name="$candidate"
+ break
+ fi
+done
+
+if [[ -z "$linear_token" ]]; then
+ echo "Langfuse identity: no Linear token available."
+ echo "Cursor Cloud: add secret LINEAR_API_KEY at https://cursor.com/dashboard/cloud-agents and start a new run."
+ exit 0
+fi
+
+response="$(
+ printf 'header = "Authorization: %s"\n' "$linear_token" |
+ curl --fail --silent --show-error --connect-timeout 3 --max-time 10 \
+ --config - \
+ https://api.linear.app/graphql \
+ -H "Content-Type: application/json" \
+ --data '{"query":"{ viewer { name email } teams { nodes { name key } } }"}' \
+ 2>/dev/null
+)" || {
+ if [[ "$mode" = "--probe" ]]; then
+ echo "linear_token: set ($linear_token_name)"
+ echo "linear_viewer: unavailable (Linear unreachable or token rejected)"
+ else
+ echo "Langfuse identity: $linear_token_name is set but Linear rejected the viewer query."
+ fi
+ exit 0
+}
+
+if [[ "$mode" = "--probe" ]]; then
+ LINEAR_RESPONSE="$response" python3 - "$linear_token_name" <<'PY'
+import json
+import os
+import sys
+
+token_name = sys.argv[1]
+try:
+ payload = json.loads(os.environ["LINEAR_RESPONSE"])
+except json.JSONDecodeError:
+ print(f"linear_token: set ({token_name})")
+ print("linear_viewer: unavailable (invalid response)")
+ sys.exit(0)
+viewer = (payload.get("data") or {}).get("viewer") or {}
+teams = (payload.get("data") or {}).get("teams", {}).get("nodes", [])
+name = viewer.get("name") or ""
+email = viewer.get("email") or ""
+langfuse_member = any(
+ team.get("key") == "LF" or team.get("name") == "Langfuse" for team in teams
+)
+
+print(f"linear_token: set ({token_name})")
+if name or email:
+ print(f"linear_viewer: {name} <{email}>")
+else:
+ print("linear_viewer: unavailable")
+print(f"langfuse_team: {'member' if langfuse_member else 'not found'}")
+PY
+ exit 0
+fi
+
+umask 077
+if ! mkdir -p "$identity_dir"; then
+ echo "Langfuse identity: could not create $identity_dir; onboarding can retry during the agent session."
+ exit 0
+fi
+chmod 700 "$identity_dir"
+
+tmp_file="$(mktemp "$identity_dir/.me.md.XXXXXX")"
+cleanup() {
+ rm -f "$tmp_file"
+}
+trap cleanup EXIT
+
+set +e
+LINEAR_RESPONSE="$response" python3 - "$identity_file" "$tmp_file" "$repo_root" <<'PY'
+import datetime
+import json
+import os
+import sys
+
+identity_file, tmp_file, repo_root = sys.argv[1:]
+try:
+ payload = json.loads(os.environ["LINEAR_RESPONSE"])
+except json.JSONDecodeError:
+ print("Langfuse identity: Linear returned an invalid response.", file=sys.stderr)
+ sys.exit(3)
+if payload.get("errors"):
+ print("Langfuse identity: Linear returned GraphQL errors.", file=sys.stderr)
+ sys.exit(3)
+
+data = payload.get("data") or {}
+viewer = data.get("viewer") or {}
+teams = (data.get("teams") or {}).get("nodes") or []
+langfuse_member = any(
+ team.get("key") == "LF" or team.get("name") == "Langfuse" for team in teams
+)
+if not langfuse_member:
+ print(
+ "Langfuse identity: Linear viewer is not a member of the Langfuse team; "
+ "leaving me.md unchanged.",
+ file=sys.stderr,
+ )
+ sys.exit(4)
+
+name = viewer.get("name") or "unknown"
+email = viewer.get("email") or "unknown"
+today = datetime.date.today().isoformat()
+content = f"""# Me, at Langfuse
+
+- **Name:** {name}
+- **Role:** maintainer
+- **GitHub:** unknown (derive from the team roster when needed)
+- **Tracker identity:** {name} <{email}>
+- **Focus:** not recorded yet β€” ask once when relevant
+- **Checkouts:** {repo_root} (langfuse)
+- **Connectors verified:** Linear API
+- *Recovered {today} from `LINEAR_API_KEY` by the repo agent bootstrap. Edit freely; delete to recover again.*
+"""
+
+with open(tmp_file, "w", encoding="utf-8") as file:
+ file.write(content)
+os.replace(tmp_file, identity_file)
+print(f"Langfuse identity: recovered {name} <{email}> at {identity_file}")
+PY
+status=$?
+set -e
+
+if [[ "$status" -ne 0 ]]; then
+ echo "Langfuse identity: recovery skipped; onboarding can retry during the agent session."
+ exit 0
+fi
diff --git a/scripts/agents/configure-langfuse-identity.test.sh b/scripts/agents/configure-langfuse-identity.test.sh
new file mode 100755
index 0000000000..d498af2be0
--- /dev/null
+++ b/scripts/agents/configure-langfuse-identity.test.sh
@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+tmpdir="$(mktemp -d)"
+
+cleanup() {
+ rm -rf "$tmpdir"
+}
+trap cleanup EXIT
+
+mkdir -p "$tmpdir/bin"
+cat >"$tmpdir/bin/curl" <<'EOF'
+#!/usr/bin/env bash
+printf '%s' "$LINEAR_FIXTURE"
+EOF
+chmod +x "$tmpdir/bin/curl"
+
+run_without_token() {
+ env \
+ -u LINEAR_API_KEY \
+ -u LINEAR_TOKEN \
+ -u LINEAR_API_TOKEN \
+ PATH="$tmpdir/bin:$PATH" \
+ LANGFUSE_CONFIG_DIR="$tmpdir/no-token" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+}
+
+no_token_output="$(run_without_token)"
+grep -Fq "add secret LINEAR_API_KEY" <<<"$no_token_output"
+test ! -e "$tmpdir/no-token/me.md"
+
+fixture='{"data":{"viewer":{"name":"Nikita Kabardin","email":"[email protected]"},"teams":{"nodes":[{"name":"Langfuse","key":"LF"}]}}}'
+identity_dir="$tmpdir/identity"
+PATH="$tmpdir/bin:$PATH" \
+LINEAR_API_KEY="test-secret-that-must-not-be-written" \
+LINEAR_FIXTURE="$fixture" \
+LANGFUSE_CONFIG_DIR="$identity_dir" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+
+grep -Fq -- "- **Name:** Nikita Kabardin" "$identity_dir/me.md"
+grep -Fq -- "- **Role:** maintainer" "$identity_dir/me.md"
+grep -Fq -- "- **Tracker identity:** Nikita Kabardin <[email protected]>" "$identity_dir/me.md"
+if grep -Fq "test-secret-that-must-not-be-written" "$identity_dir/me.md"; then
+ echo "Identity file leaked the Linear token"
+ exit 1
+fi
+
+printf '\nuser edit\n' >>"$identity_dir/me.md"
+PATH="$tmpdir/bin:$PATH" \
+LINEAR_API_KEY="test-secret-that-must-not-be-written" \
+LINEAR_FIXTURE="$fixture" \
+LANGFUSE_CONFIG_DIR="$identity_dir" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+grep -Fq "user edit" "$identity_dir/me.md"
+
+outsider_fixture='{"data":{"viewer":{"name":"Outside User","email":"[email protected]"},"teams":{"nodes":[{"name":"Another Team","key":"OTHER"}]}}}'
+PATH="$tmpdir/bin:$PATH" \
+LINEAR_API_KEY="another-test-secret" \
+LINEAR_FIXTURE="$outsider_fixture" \
+LANGFUSE_CONFIG_DIR="$tmpdir/outsider" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+test ! -e "$tmpdir/outsider/me.md"
+
+# Recovery must lock the identity directory to the owner even when the
+# caller inherited a permissive umask.
+(
+ umask 000
+ PATH="$tmpdir/bin:$PATH" \
+ LINEAR_API_KEY="test-secret-that-must-not-be-written" \
+ LINEAR_FIXTURE="$fixture" \
+ LANGFUSE_CONFIG_DIR="$tmpdir/loose-umask" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+)
+dir_mode="$(stat -c %a "$tmpdir/loose-umask")"
+if [[ "$dir_mode" != "700" ]]; then
+ echo "Identity directory mode is $dir_mode, expected 700"
+ exit 1
+fi
+
+# A write that cannot create the identity directory must still exit 0 so
+# postinstall and Cloud boot cannot fail the install for a missing HOME.
+touch "$tmpdir/not-a-directory"
+set +e
+mkdir_fail_status=0
+PATH="$tmpdir/bin:$PATH" \
+LINEAR_API_KEY="test-secret-that-must-not-be-written" \
+LINEAR_FIXTURE="$fixture" \
+LANGFUSE_CONFIG_DIR="$tmpdir/not-a-directory" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"
+mkdir_fail_status=$?
+set -e
+if [[ "$mkdir_fail_status" -ne 0 ]]; then
+ echo "Identity recovery exited $mkdir_fail_status when mkdir failed"
+ exit 1
+fi
+
+# The onboarding probe must still report the GitHub signals when the Linear
+# side fails outright, so a blocked egress path cannot truncate step 1.
+probe_tree="$tmpdir/probe-tree"
+mkdir -p "$probe_tree/.agents/skills/langfuse-onboarding/scripts" "$probe_tree/scripts/agents"
+cp \
+ "$repo_root/.agents/skills/langfuse-onboarding/scripts/whoami.sh" \
+ "$probe_tree/.agents/skills/langfuse-onboarding/scripts/whoami.sh"
+cat >"$probe_tree/scripts/agents/configure-langfuse-identity.sh" <<'EOF'
+#!/usr/bin/env bash
+echo "stub identity probe failed" >&2
+exit 1
+EOF
+chmod +x "$probe_tree/scripts/agents/configure-langfuse-identity.sh"
+
+cat >"$tmpdir/bin/gh" <<'EOF'
+#!/usr/bin/env bash
+echo "gh: Resource not accessible by integration (HTTP 403)" >&2
+exit 1
+EOF
+chmod +x "$tmpdir/bin/gh"
+
+probe_output="$(
+ PATH="$tmpdir/bin:$PATH" \
+ HOME="$tmpdir/probe-home" \
+ bash "$probe_tree/.agents/skills/langfuse-onboarding/scripts/whoami.sh"
+)"
+grep -Fq "linear_viewer: unavailable" <<<"$probe_output"
+grep -Fq "gh_user: unavailable" <<<"$probe_output"
+
+# A rejected or unreachable Linear endpoint reports in the probe's own label
+# format rather than aborting the probe.
+cat >"$tmpdir/bin/curl" <<'EOF'
+#!/usr/bin/env bash
+exit 7
+EOF
+chmod +x "$tmpdir/bin/curl"
+
+unreachable_output="$(
+ PATH="$tmpdir/bin:$PATH" \
+ LINEAR_API_KEY="unused-test-secret" \
+ LANGFUSE_CONFIG_DIR="$tmpdir/unreachable" \
+ bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" --probe
+)"
+grep -Fq "linear_token: set (LINEAR_API_KEY)" <<<"$unreachable_output"
+grep -Fq "linear_viewer: unavailable" <<<"$unreachable_output"
+test ! -e "$tmpdir/unreachable/me.md"
+
+echo "Langfuse identity recovery tests passed"
diff --git a/scripts/agents/start-cursor-cloud.sh b/scripts/agents/start-cursor-cloud.sh
index a99d51c009..c12f1012e5 100755
--- a/scripts/agents/start-cursor-cloud.sh
+++ b/scripts/agents/start-cursor-cloud.sh
@@ -7,6 +7,11 @@ compose_file="${CURSOR_COMPOSE_FILE:-$repo_root/docker-compose.build.yml}"
wait_timeout="${CURSOR_COMPOSE_WAIT_TIMEOUT_SECONDS:-600}"
compose_project_name="${CURSOR_COMPOSE_PROJECT_NAME:-langfuse-cursor}"
+# Environment builds do not rerun install when a new agent boots. Recover the
+# developer identity before starting services so every fresh Cloud run has it.
+# Best-effort: a missing HOME or a blocked Linear route must not abort the stack.
+bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" || true
+
# The workspace .env is for processes running on the host and therefore uses
# localhost service URLs. Compose services need container-network hostnames.
# Start from a clean environment and explicitly preserve only Docker and
diff --git a/scripts/agents/start-cursor-cloud.test.sh b/scripts/agents/start-cursor-cloud.test.sh
index 3c9ba695ff..9de2d8cc48 100755
--- a/scripts/agents/start-cursor-cloud.test.sh
+++ b/scripts/agents/start-cursor-cloud.test.sh
@@ -67,6 +67,10 @@ chmod +x \
# Leave $test_docker_socket missing so ensure_docker_socket_reachable must
# repair the parent directory before the daemon probe loop.
PATH="$tmpdir/bin:$PATH" \
+LANGFUSE_CONFIG_DIR="$tmpdir/identity" \
+LINEAR_API_KEY="" \
+LINEAR_TOKEN="" \
+LINEAR_API_TOKEN="" \
DATABASE_URL="postgresql://external.example:5432/production" \
CLICKHOUSE_URL="https://external.example:8443" \
CURSOR_COMPOSE_WAIT_TIMEOUT_SECONDS=321 \
diff --git a/scripts/postinstall.sh b/scripts/postinstall.sh
index 0fffb60121..b691dc0274 100644
--- a/scripts/postinstall.sh
+++ b/scripts/postinstall.sh
@@ -24,3 +24,9 @@ pnpm run agents:sync
# concern, and failing it here would break `pnpm i` and with it every CI job
# that installs. The lint job runs the full check.
node scripts/agents/sync-agent-shims.mjs --check
+
+# Recover the developer identity in every newly installed worktree. This is
+# best-effort: contributors and local installs commonly have no Linear token.
+if [[ -f "scripts/agents/configure-langfuse-identity.sh" ]]; then
+ bash scripts/agents/configure-langfuse-identity.sh || true
+fi