@enrichlayer/el-linear 1.10.0 → 1.15.0

package/dist/commands/batch.js

@@ -1,14 +1,12 @@
-import { resolveAssignee, resolveLabels, resolveTeam, } from "../config/resolver.js";
-import { GraphQLIssuesService } from "../utils/graphql-issues-service.js";
-import { createGraphQLService } from "../utils/graphql-service.js";
-import { createLinearService } from "../utils/linear-service.js";
+import { resolveAssignee, resolveLabels, resolveMember, resolveTeam, } from "../config/resolver.js";
+import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { splitList } from "../utils/validators.js";
 /**
  * Parse the --filter string into structured search arguments.
- * Format: "status:Backlog team:DEV label:Bug assignee:Alice project:Sprint12"
+ * Format: "status:Backlog team:DEV label:Bug assignee:Alice delegate:Claude project:Sprint12"
  */
 function parseFilterString(filter) {
     const result = {};
@@ -30,21 +28,28 @@ function parseFilterString(filter) {
  * Returns LinearIssue[] so we can show a preview.
  */
 async function resolveTargetIssues(options, rootOpts) {
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     if (options.issues) {
         const ids = splitList(options.issues);
         return Promise.all(ids.map((id) => issuesService.getIssueById(id)));
     }
     if (options.filter) {
         const filters = parseFilterString(options.filter);
+        // Typed as SearchIssueArgs (not Record<string, unknown>) so a future
+        // rename of any field — like the DEV-4068 T4 `projectId` → `project`
+        // migration — surfaces here at compile time instead of silently
+        // dropping the filter.
         const searchArgs = {
             teamId: filters.team ? resolveTeam(filters.team) : undefined,
             assigneeId: filters.assignee
                 ? await resolveAssignee(filters.assignee, rootOpts)
                 : undefined,
-            projectId: filters.project || undefined,
+            delegateId: filters.delegate
+                ? resolveMember(filters.delegate)
+                : undefined,
+            project: filters.project
+                ? { kind: "id", id: filters.project }
+                : undefined,
             labelNames: filters.label ? splitList(filters.label) : undefined,
             status: filters.status ? splitList(filters.status) : undefined,
             limit: 50,
@@ -117,9 +122,7 @@ async function handleBatchAssign(options, command) {
         });
         return;
     }
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, assigneeId }, "adding"));
     outputSuccess({
         action: "assign",
@@ -164,9 +167,7 @@ async function handleBatchLabel(options, command) {
         });
         return;
     }
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     const removeLower = removeLabels.map((l) => l.toLowerCase());
     const { results } = await executeBatch(issues, (issue) => {
         // Filter out labels to remove (by name, case-insensitive)
@@ -218,9 +219,7 @@ async function handleBatchMove(options, command) {
         });
         return;
     }
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, projectId: options.project }, "adding"));
     outputSuccess({
         action: "move",
@@ -254,9 +253,7 @@ async function handleBatchStatus(options, command) {
         });
         return;
     }
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     const { results } = await executeBatch(issues, (issue) => issuesService.updateIssue({ id: issue.identifier, statusId: options.status }, "adding"));
     outputSuccess({
         action: "status",

package/dist/commands/comments.js

@@ -18,13 +18,13 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
 function readBody(options) {
-    if (options.file) {
-        return readFileSync(options.file, "utf-8");
+    if (options.bodyFile) {
+        return readFileSync(options.bodyFile, "utf-8");
     }
     if (options.body) {
         return options.body;
     }
-    throw new Error("Either --body or --file is required");
+    throw new Error("Either --body or --body-file is required");
 }
 async function fetchSelfUserId(graphQLService) {
     try {
@@ -250,7 +250,7 @@ export function setupCommentsCommands(program) {
         .description("Create new comment on issue.")
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.\nBare references to known team members (e.g. 'Dima') are auto-converted to @mentions — pass --no-auto-mention to disable.\nIssue identifiers (e.g. DEV-123) are wrapped as markdown links and added as 'related' relations on the parent issue — pass --no-auto-link to disable.")
         .option("--body <body>", "comment body (inline)")
-        .option("--file <path>", "read comment body from file")
+        .option("--body-file <path>", "read comment body from file")
         .option("--no-auto-mention", "do not auto-convert bare team-member names to @mentions")
         .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
         .option("--footer <text>", "text appended to the comment body (overrides config.messageFooter)")
@@ -260,7 +260,7 @@ export function setupCommentsCommands(program) {
         .command("update <commentId>")
         .description("Update an existing comment.")
         .option("--body <body>", "new comment body (inline)")
-        .option("--file <path>", "read new comment body from file")
+        .option("--body-file <path>", "read new comment body from file")
         .option("--no-auto-mention", "do not auto-convert bare team-member names to @mentions")
         .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
         .action(handleAsyncCommand(handleUpdateComment));

package/dist/commands/config.js

@@ -1,5 +1,47 @@
-import { loadConfig } from "../config/config.js";
-import { outputSuccess } from "../utils/output.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getActiveTeamConfigInfo, getActiveTeamConfigPath, loadConfig, loadLocalConfig, } from "../config/config.js";
+import { resolveActiveProfile } from "../config/paths.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { updateConfig } from "./init/shared.js";
+/**
+ * Expand a leading `~` to the user's home directory. Shells expand `~` before
+ * the command sees it, but a literal `~/...` pasted from documentation reaches
+ * Node verbatim. We handle it so `el-linear config team set-path ~/git/...`
+ * works regardless of whether the shell did the expansion first.
+ */
+function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Render the team-config source token returned by `getActiveTeamConfigInfo()`
+ * as a human-readable string for `config team show`. Kept next to the command
+ * (not in `config/config.ts`) so the wire format is owned by the renderer,
+ * not the resolver. DEV-4258.
+ */
+function sourceLabel(source) {
+    switch (source) {
+        case "env":
+            return "EL_LINEAR_TEAM_CONFIG env var";
+        case "personal":
+            return "teamConfigPath in personal config";
+        case "marker":
+            return "auto-discovered via ~/.config/el-tools-root";
+        case null:
+            return null;
+    }
+}
+const LOCAL_SETTABLE_KEYS = [
+    "assigneeEmail",
+    "defaultAssignee",
+    "defaultPriority",
+    "cacheTTLSeconds",
+];
 export function setupConfigCommands(program) {
     const config = program
         .command("config")
@@ -7,9 +49,140 @@ export function setupConfigCommands(program) {
     config.action(() => config.help());
     config
         .command("show")
-        .description("Show resolved configuration")
-        .addHelpText("after", "\nDumps the merged config from ~/.config/el-linear/config.json.\n\nExamples:\n  el-linear config show")
+        .description("Show resolved configuration (team file → personal config → local overrides)")
+        .addHelpText("after", "\nDumps the merged config from the active team file + config.json + local.json.\n\nExamples:\n  el-linear config show")
+        .action(() => {
+        const data = loadConfig();
+        const teamConfig = getActiveTeamConfigPath();
+        const local = loadLocalConfig();
+        const out = { data };
+        if (teamConfig)
+            out.teamConfig = teamConfig;
+        if (Object.keys(local).length > 0)
+            out.local = local;
+        outputSuccess(out);
+    });
+    const local = config
+        .command("local")
+        .description("Manage user-local config overrides (local.json)");
+    local.action(() => local.help());
+    local
+        .command("show")
+        .description("Show the raw contents of local.json")
+        .addHelpText("after", `\nShows ~/.config/el-linear/local.json (or the per-profile equivalent).\n\nExamples:\n  el-linear config local show`)
+        .action(() => {
+        outputSuccess({ data: loadLocalConfig() });
+    });
+    const team = config
+        .command("team")
+        .description("Manage the shared team config layer (teamConfigPath in personal config)");
+    team.action(() => team.help());
+    team
+        .command("show")
+        .description("Show the active team config layer: path, source (env var, personal config, or auto-discovered marker), file status, top-level keys it contributes")
+        .addHelpText("after", "\nResolves the team config in the same order loadConfig() does:\n  EL_LINEAR_TEAM_CONFIG (env)  >  teamConfigPath (personal config)  >  ~/.config/el-tools-root marker\n\nExamples:\n  el-linear config team show")
         .action(() => {
-        outputSuccess({ data: loadConfig() });
+        const info = getActiveTeamConfigInfo();
+        const teamPath = info.path;
+        const source = sourceLabel(info.source);
+        const out = {
+            teamConfigPath: teamPath ?? null,
+            source,
+        };
+        if (teamPath) {
+            try {
+                const raw = fs.readFileSync(teamPath, "utf8");
+                const parsed = JSON.parse(raw);
+                out.exists = true;
+                out.valid = true;
+                out.providedKeys = Object.keys(parsed).sort();
+            }
+            catch (err) {
+                out.exists = fs.existsSync(teamPath);
+                out.valid = false;
+                out.error = err.message;
+            }
+        }
+        outputSuccess({ data: out });
     });
+    team
+        .command("set-path <path>")
+        .description("Write teamConfigPath into personal config.json. Path is resolved to an absolute path. The target file must exist and be valid JSON — a pointer to a missing or broken file is footgun-shaped and refused.")
+        .addHelpText("after", "\nUse this when adopting a shared team config (e.g. one checked into a tools repo):\n  el-linear config team set-path ~/git/enrichlayer/tools/config/el-linear.shared.json\n\nRelative paths resolve against the current working directory; absolute paths are stored as-is. EL_LINEAR_TEAM_CONFIG in the environment still overrides the personal field when both are set — a warning surfaces in that case.")
+        .action(handleAsyncCommand(async (rawPath) => {
+        const resolved = path.resolve(expandHome(rawPath));
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`Team config file not found at ${resolved}. Create the file (or fix the path) before pointing personal config at it.`);
+        }
+        try {
+            JSON.parse(fs.readFileSync(resolved, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Team config at ${resolved} is not valid JSON: ${err.message}`);
+        }
+        await updateConfig((current) => ({
+            ...current,
+            teamConfigPath: resolved,
+        }));
+        const envOverride = process.env.EL_LINEAR_TEAM_CONFIG?.trim() || undefined;
+        if (envOverride !== undefined && envOverride !== resolved) {
+            outputWarning(`EL_LINEAR_TEAM_CONFIG=${envOverride} is set in this shell and overrides the personal config field. Unset it (or align it) for the persistent setting to take effect.`);
+        }
+        outputSuccess({
+            data: {
+                teamConfigPath: resolved,
+                written: resolveActiveProfile().configPath,
+            },
+        });
+    }));
+    team
+        .command("clear")
+        .description("Remove teamConfigPath from personal config.json. EL_LINEAR_TEAM_CONFIG (env) is unaffected and continues to override if set.")
+        .action(handleAsyncCommand(async () => {
+        let removed;
+        await updateConfig((current) => {
+            removed = current.teamConfigPath;
+            const { teamConfigPath: _drop, ...rest } = current;
+            return rest;
+        });
+        const envOverride = process.env.EL_LINEAR_TEAM_CONFIG?.trim() || undefined;
+        if (envOverride !== undefined) {
+            outputWarning(`EL_LINEAR_TEAM_CONFIG=${envOverride} is still set in this shell; it overrides the personal field and remains active until unset.`);
+        }
+        outputSuccess({
+            data: {
+                cleared: true,
+                previousTeamConfigPath: removed ?? null,
+                written: resolveActiveProfile().configPath,
+            },
+        });
+    }));
+    local
+        .command("set <key> <value>")
+        .description(`Set a key in local.json. Keys: ${LOCAL_SETTABLE_KEYS.join(", ")}`)
+        .addHelpText("after", `\nAllowed keys:\n  assigneeEmail    — your Linear account email (used as default --assignee)\n  defaultAssignee  — alias / display name / email / UUID\n  defaultPriority  — none|urgent|high|medium|normal|low\n  cacheTTLSeconds  — integer seconds (0 = disable cache)\n\nExamples:\n  el-linear config local set assigneeEmail you@example.com\n  el-linear config local set defaultPriority medium\n  el-linear config local set cacheTTLSeconds 0`)
+        .action(handleAsyncCommand(async (key, value) => {
+        if (!LOCAL_SETTABLE_KEYS.includes(key)) {
+            throw new Error(`Unknown local config key "${key}". Allowed: ${LOCAL_SETTABLE_KEYS.join(", ")}`);
+        }
+        const active = resolveActiveProfile();
+        const localPath = active.localConfigPath;
+        let existing = {};
+        if (fs.existsSync(localPath)) {
+            try {
+                existing = JSON.parse(fs.readFileSync(localPath, "utf8"));
+            }
+            catch {
+                // overwrite a corrupt file
+            }
+        }
+        const typedValue = key === "cacheTTLSeconds" ? Number(value) : value;
+        if (key === "cacheTTLSeconds" && Number.isNaN(typedValue)) {
+            throw new Error(`cacheTTLSeconds must be an integer, got "${value}"`);
+        }
+        const updated = { ...existing, [key]: typedValue };
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        fs.writeFileSync(localPath, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+        outputSuccess({ data: updated });
+    }));
 }

package/dist/commands/init/aliases.js

@@ -22,7 +22,7 @@ const USERS_QUERY = /* GraphQL */ `
   }
 `;
 export async function fetchAllUsers(token) {
-    const service = new GraphQLService(token);
+    const service = new GraphQLService({ apiKey: token });
     const out = [];
     let after;
     for (;;) {

package/dist/commands/init/defaults.d.ts

@@ -6,7 +6,7 @@
  * with no input is a no-op.
  */
 import { type WizardConfig } from "./shared.js";
-export interface DefaultsStepResult {
+interface DefaultsStepResult {
     defaultLabels: string[] | undefined;
     /**
      * Default assignee identifier (alias / display name / email / UUID — same
@@ -40,3 +40,4 @@ export interface DefaultsStepResult {
     cacheTTLSeconds: number | undefined;
 }
 export declare function runDefaultsStep(existing: WizardConfig): Promise<DefaultsStepResult>;
+export {};

package/dist/commands/init/index.js

@@ -14,10 +14,11 @@
  * Skip is the default at every prompt. Only `init token` is required for a
  * first-time setup; everything else can be skipped and revisited later.
  */
+import { validateOAuthActor, } from "../../auth/oauth-client.js";
 import { mergeAliasesIntoConfig, runAliasesImport, runAliasesStep, } from "./aliases.js";
 import { runDefaultsStep } from "./defaults.js";
 import { runOAuthRevoke, runOAuthStep } from "./oauth.js";
-import { assignDefined, printStep, readConfig, writeConfig, } from "./shared.js";
+import { assignDefined, printStep, readConfig, updateConfig, } from "./shared.js";
 import { runTokenStep } from "./token.js";
 import { runWorkspaceStep } from "./workspace.js";
 /**
@@ -60,6 +61,7 @@ export function setupInitCommands(program) {
         .command("oauth")
         .description("Authorize via OAuth 2.0 (PKCE) — alternative to a personal API token")
         .option("--force", "ignore existing tokens; re-authorize unconditionally")
+        .option("--actor <actor>", "OAuth actor: user (default) or app for agents/service accounts", validateOAuthActor)
         .option("--revoke", "revoke and remove the stored OAuth tokens")
         .option("--no-browser", "skip the browser-open + localhost listener; paste the code manually")
         .option("--port <port>", "localhost callback port (default 8765)", (value) => Number.parseInt(value, 10))
@@ -72,6 +74,7 @@ export function setupInitCommands(program) {
             return;
         }
         await runOAuthStep({
+            actor: options.actor,
             force: options.force ?? false,
             // commander's `--no-browser` produces `browser: false`.
             noBrowser: options.browser === false,
@@ -87,14 +90,15 @@ export function setupInitCommands(program) {
         const existing = await readConfig();
         printStep("workspace", "Workspace defaults");
         const ws = await runWorkspaceStep(tokenResult.token, tokenResult.viewer.organization.urlKey, existing);
-        const merged = assignDefined(existing, {
+        // Re-read inside the lock so a concurrent `init <step>` that
+        // finished while we were prompting isn't clobbered (DEV-4066).
+        await updateConfig((current) => assignDefined(current, {
             defaultTeam: ws.defaultTeam,
-            teams: { ...(existing.teams ?? {}), ...ws.teams },
-            // Don't clobber a manual urlKey override — same idempotency
-            // rule as the full wizard.
-            workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
-        });
-        await writeConfig(merged);
+            teams: { ...(current.teams ?? {}), ...ws.teams },
+            // Don't clobber a manual urlKey override — same
+            // idempotency rule as the full wizard.
+            workspaceUrlKey: current.workspaceUrlKey ?? ws.workspaceUrlKey,
+        }));
         console.log("  ✓ Workspace defaults saved.");
     }));
     init
@@ -123,8 +127,9 @@ export function setupInitCommands(program) {
             console.log("  No alias changes — config unchanged.");
             return;
         }
-        const merged = mergeAliasesIntoConfig(existing, updates);
-        await writeConfig(merged);
+        // Re-merge under the lock against the latest on-disk state so
+        // a concurrent step's write isn't lost (DEV-4066).
+        await updateConfig((current) => mergeAliasesIntoConfig(current, updates));
         console.log(`  ✓ Updated aliases for ${updates.size} user(s).`);
     }));
     init
@@ -134,15 +139,16 @@ export function setupInitCommands(program) {
         const existing = await readConfig();
         printStep("defaults", "Defaults");
         const result = await runDefaultsStep(existing);
-        const merged = assignDefined(existing, {
+        // Re-read inside the lock so a concurrent `init <step>` that
+        // finished while we were prompting isn't clobbered (DEV-4066).
+        await updateConfig((current) => assignDefined(current, {
             defaultLabels: result.defaultLabels,
             defaultAssignee: result.defaultAssignee,
             defaultPriority: result.defaultPriority,
             statusDefaults: result.statusDefaults,
             terms: result.terms,
             cacheTTLSeconds: result.cacheTTLSeconds,
-        });
-        await writeConfig(merged);
+        }));
         console.log("  ✓ Defaults saved.");
     }));
 }
@@ -170,33 +176,37 @@ async function runFullWizardImpl(options) {
     // Step 4: defaults
     printStep("4/4", "Defaults");
     const defaults = await runDefaultsStep(existing);
-    // Merge everything and write atomically at the end.
+    // Merge everything and write atomically at the end, under the config
+    // lock so a parallel `init <step>` invocation can't clobber us
+    // (DEV-4066). Re-read inside the lock to merge on the latest state.
     // Idempotency rule: only write a key when the user explicitly changed it.
-    // `existing.X ?? new.X` preserves any manual override the user may have
+    // `current.X ?? new.X` preserves any manual override the user may have
     // in config.json (self-hosted Linear urlKey, custom default team, etc.).
     // `assignDefined` skips undefined values so the resulting object's own-
     // property set matches what JSON.stringify would actually serialize.
-    let merged = assignDefined(existing, {
-        // defaults step: result is `existing.X` itself when the user skipped
-        // the edit branch, so direct assignment is safe.
-        defaultLabels: defaults.defaultLabels,
-        defaultAssignee: defaults.defaultAssignee,
-        defaultPriority: defaults.defaultPriority,
-        statusDefaults: defaults.statusDefaults,
-        terms: defaults.terms,
-        cacheTTLSeconds: defaults.cacheTTLSeconds,
-        // workspace step: `ws.defaultTeam` may be the existing value (user
-        // skipped) or a new pick.
-        defaultTeam: ws.defaultTeam,
-        // Always merge the team UUID cache (additive, not destructive).
-        teams: { ...(existing.teams ?? {}), ...ws.teams },
-        // workspaceUrlKey: never clobber an existing manual override.
-        workspaceUrlKey: existing.workspaceUrlKey ?? ws.workspaceUrlKey,
+    await updateConfig((current) => {
+        let merged = assignDefined(current, {
+            // defaults step: result is `existing.X` itself when the user
+            // skipped the edit branch, so direct assignment is safe.
+            defaultLabels: defaults.defaultLabels,
+            defaultAssignee: defaults.defaultAssignee,
+            defaultPriority: defaults.defaultPriority,
+            statusDefaults: defaults.statusDefaults,
+            terms: defaults.terms,
+            cacheTTLSeconds: defaults.cacheTTLSeconds,
+            // workspace step: `ws.defaultTeam` may be the existing value (user
+            // skipped) or a new pick.
+            defaultTeam: ws.defaultTeam,
+            // Always merge the team UUID cache (additive, not destructive).
+            teams: { ...(current.teams ?? {}), ...ws.teams },
+            // workspaceUrlKey: never clobber an existing manual override.
+            workspaceUrlKey: current.workspaceUrlKey ?? ws.workspaceUrlKey,
+        });
+        if (aliasUpdates.size > 0) {
+            merged = mergeAliasesIntoConfig(merged, aliasUpdates);
+        }
+        return merged;
     });
-    if (aliasUpdates.size > 0) {
-        merged = mergeAliasesIntoConfig(merged, aliasUpdates);
-    }
-    await writeConfig(merged);
     console.log("\n✓ Setup complete.");
     console.log("  Token:  ~/.config/el-linear/token (mode 0600)");
     console.log("  Config: ~/.config/el-linear/config.json");

package/dist/commands/init/oauth.d.ts

@@ -18,6 +18,7 @@
  * revoke before doing anything else.
  */
 import { runLocalhostCallback } from "../../auth/oauth-callback.js";
+import { type OAuthActor } from "../../auth/oauth-client.js";
 import { type OAuthState } from "../../auth/oauth-storage.js";
 import { type FetchLike } from "../../auth/oauth-token.js";
 interface ViewerResponse {
@@ -33,6 +34,8 @@ interface ViewerResponse {
     };
 }
 export interface OAuthStepOptions {
+    /** OAuth actor mode: `user` (default) or `app` for agents/service accounts. */
+    actor?: OAuthActor;
     /** Force re-authorization even if existing state is valid. */
     force?: boolean;
     /** Skip the localhost listener; use the headless code-paste prompt. */
@@ -56,7 +59,7 @@ export interface OAuthStepOptions {
     /** Test seam for `viewer` validation against the new bearer token. */
     validateViewer?: (oauthToken: string) => Promise<ViewerResponse["viewer"]>;
 }
-export interface OAuthStepResult {
+interface OAuthStepResult {
     state: OAuthState;
     viewer: ViewerResponse["viewer"];
 }

package/dist/commands/init/oauth.js

@@ -21,7 +21,7 @@ import { spawn } from "node:child_process";
 import { checkbox, input, password, select } from "@inquirer/prompts";
 import { readTeamOAuthConfig } from "../../auth/oauth-app-config.js";
 import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-callback.js";
-import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateScopes, } from "../../auth/oauth-client.js";
+import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateActorScopes, validateScopes, } from "../../auth/oauth-client.js";
 import { promptForPastedCode } from "../../auth/oauth-headless.js";
 import { clearOAuthState, OAUTH_STATE_VERSION, readOAuthState, writeOAuthState, } from "../../auth/oauth-storage.js";
 import { exchangeCodeForTokens, revokeToken, } from "../../auth/oauth-token.js";
@@ -128,7 +128,11 @@ async function promptRegistration(defaults) {
     logLine("");
     logLine(TS(`Register a Linear OAuth app: ${REGISTRATION_URL}`));
     logLine(TS(`Set the redirect URL to: http://localhost:${defaults.port ?? DEFAULT_PORT}${DEFAULT_CALLBACK_PATH}`));
-    logLine(TS("Then paste the client_id (and client_secret, if your app is configured as confidential)."));
+    logLine(TS(`Then paste the client_id (and client_secret, if your app is configured as confidential).`));
+    logLine(TS(`Actor: ${defaults.actor}.`));
+    if (defaults.actor === "user") {
+        logLine(TS("Use --actor app for agent/service-account app user tokens."));
+    }
     logLine("");
     const port = Number.parseInt(await input({
         message: "Localhost callback port:",
@@ -159,24 +163,34 @@ async function promptRegistration(defaults) {
         })),
         validate: (selections) => selections.length > 0 || "Pick at least one scope",
     }));
+    const validatedScopes = validateScopes(scopes);
+    validateActorScopes(defaults.actor, validatedScopes);
     return {
+        actor: defaults.actor,
         clientId,
         clientSecret: clientSecret || undefined,
         port,
-        scopes: validateScopes(scopes),
+        scopes: validatedScopes,
     };
 }
 async function resolveRegistration(defaults) {
     const teamConfig = await readTeamOAuthConfig();
     if (!teamConfig) {
-        return promptRegistration({ port: defaults.manualPort });
+        return promptRegistration({
+            actor: defaults.actor ?? "user",
+            port: defaults.manualPort,
+        });
     }
+    const actor = defaults.actor ?? teamConfig.actor;
     const port = defaults.requestedPort ?? teamConfig.redirectPort;
     logLine("");
     logLine(TS(`Using Linear OAuth app defaults from ${teamConfig.sourcePath}.`));
+    logLine(TS(`Actor: ${actor}.`));
     logLine(TS(`Callback URL: http://localhost:${port}${DEFAULT_CALLBACK_PATH}`));
     logLine("");
+    validateActorScopes(actor, teamConfig.scopes);
     return {
+        actor,
         clientId: teamConfig.clientId,
         port,
         scopes: teamConfig.scopes,
@@ -231,6 +245,7 @@ export async function runOAuthStep(options = {}) {
         // Both `reauth` and `revoked` fall through to the re-auth flow.
     }
     const reg = await resolveRegistration({
+        actor: options.actor,
         manualPort: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
         requestedPort: options.port,
     });
@@ -243,6 +258,7 @@ export async function runOAuthStep(options = {}) {
         scopes: reg.scopes,
         state,
         codeChallenge: pkce.challenge,
+        actor: reg.actor,
     });
     logLine("");
     logLine(TS("Opening your browser to authorize…"));
@@ -292,6 +308,7 @@ export async function runOAuthStep(options = {}) {
     }, options.fetchImpl);
     const newState = {
         v: OAUTH_STATE_VERSION,
+        actor: reg.actor,
         clientId: reg.clientId,
         clientSecret: reg.clientSecret,
         registeredRedirectUri: redirectUri,
@@ -304,6 +321,7 @@ export async function runOAuthStep(options = {}) {
     };
     logLine(TS("Validating against viewer…"));
     const viewer = await validateViewer(newState.accessToken);
+    newState.viewerId = viewer.id;
     await writeOAuthState(newState);
     logLine(TS(`✓ Authorized as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`));
     return { state: newState, viewer };

package/dist/commands/init/shared.d.ts

@@ -29,8 +29,30 @@ type DeepPartial<T> = T extends Array<infer _U> ? T : T extends object ? {
  */
 export type WizardConfig = DeepPartial<ElLinearConfig>;
 export declare function ensureConfigDir(): Promise<void>;
-export declare function readConfig(): Promise<WizardConfig>;
-export declare function writeConfig(config: WizardConfig): Promise<void>;
+export declare function readConfig(configPath?: string): Promise<WizardConfig>;
+export declare function writeConfig(config: WizardConfig, configPath?: string): Promise<void>;
+/**
+ * Run a read-modify-write update on the active profile's config.json under
+ * an exclusive file lock. The mutator receives the latest on-disk config
+ * (re-read inside the lock), and its return value is written back atomically.
+ *
+ * Use this anywhere two parallel wizard invocations could race a
+ * read → mutate → write sequence. Each `el-linear init <step>` re-reads the
+ * config and merges its slice; without serialization, the slower writer's
+ * mutation would clobber the faster writer's already-persisted changes.
+ *
+ * The interactive prompt phase MUST run outside the lock — prompts can sit
+ * waiting for user input longer than the lock's stale window. Seed prompts
+ * with a cheap pre-read, do the prompts, then call `updateConfig` with a
+ * mutator that re-reads and merges your slice on top of the latest state.
+ *
+ * The active-profile path is snapshotted ONCE at entry and threaded through
+ * `readConfig` + `writeConfig`. A theoretical mid-update profile switch
+ * (`--profile` is bound by the commander preAction before any subcommand
+ * runs, so this can't happen via the CLI today) can't cause a lock-A /
+ * read-or-write-B mismatch.
+ */
+export declare function updateConfig(mutator: (current: WizardConfig) => WizardConfig | Promise<WizardConfig>): Promise<void>;
 export declare function readToken(): Promise<string | null>;
 /**
  * Write the token to disk with mode 0600.