elanous 0.2.41 → 0.2.43

package/src/compact/auto.ts

@@ -31,8 +31,15 @@ export function shouldAutoCompact(
   messages: MessageLike[],
   modelId: string | undefined,
   config: ChatAutoCompactConfig,
+  observedInputTokens?: number,
 ): AutoCompactDecision {
-  const usedTokens = estimateMessagesTokens(messages);
+  const hasObservedInputTokens = typeof observedInputTokens === 'number'
+    && Number.isFinite(observedInputTokens)
+    && observedInputTokens >= 0;
+  const estimatedTokens = estimateMessagesTokens(messages);
+  // Provider usage captures model/tokenizer overhead; current history also
+  // includes tool output appended since that provider response.
+  const usedTokens = hasObservedInputTokens ? Math.max(observedInputTokens, estimatedTokens) : estimatedTokens;
   const windowTokens = resolveModelContextWindow(modelId) ?? inferContextWindow(modelId);
   const configuredBudget = config.workingBudgetTokens;
   const budgetTokens = typeof configuredBudget === 'number'

package/src/config.ts

@@ -7,6 +7,7 @@ import { listSshHosts } from './ssh/ssh-hosts.js';
 import { isInstalledPackagePath } from './instance/installed-package.js';
 import { defaultObsidianVault } from './obsidian/default-vault.js';
 import { OPENGATEWAY_DEFAULT_MODEL } from './llm/opengateway-models.js';
+import { SERVICE_KEY_CATALOG } from './setup/service-key-catalog.js';
 
 // ── User config ──
 export const REMOTE_HOME = homedir();
@@ -191,10 +192,11 @@ export function refreshKeyFromCache(envName: string): boolean {
  * (음성 STT/TTS 등) plist 에서 키만 빼면 조용히 죽는다 ⇒ 부팅 한 곳에서 캐시를 env 에 싣는다(규약 = 캐시 우선 · ⓐⓑ 동일).
  * 자식 프로세스도 이 env 를 물려받는다. 반환 = 캐시로 채운 이름(값은 절대 안 싣는다).
  */
-export const DAEMON_KEY_ENV_NAMES = [
+export const DAEMON_KEY_ENV_NAMES = [...new Set([
   'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'XAI_API_KEY', 'OPENROUTER_API_KEY', 'OPENGATEWAY_API_KEY',
   'ELANOUS_OPENAI_RELAY_SHARED_SECRET',
-] as const;
+  ...SERVICE_KEY_CATALOG.flatMap(item => item.envNames),
+])];
 
 export function hydrateEnvFromKeyCache(names: readonly string[] = DAEMON_KEY_ENV_NAMES, env: NodeJS.ProcessEnv = process.env): string[] {
   const filled: string[] = [];

package/src/connectors/linear-daily-progress.ts

@@ -0,0 +1,228 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { debug } from '../debug/log.js';
+import { listChecklist, checklistHistory, checklistDevVersion, type Checklist, type ChecklistHistory } from '../release-loop/checklist.js';
+import { DecisionLedger, type DecisionEntry } from '../decisions/decision-ledger.js';
+import { commentLinearIssue } from './linear.js';
+
+const ISSUE_REF = /\bELA-\d+\b/g;
+const BODY_MARKER = '<!-- elanous-daily-progress:';
+const WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+export interface LinearDailyProgressSummary {
+  identifier: string;
+  day: string;
+  body: string;
+  contentHash: string;
+}
+export interface LinearDailyProgressResult {
+  posted: number;
+  skipped: number;
+  failed: number;
+  dryRun: boolean;
+  plan: Array<{ identifier: string; day: string; contentHash: string; body: string; status: 'dry-run' | 'posted' | 'duplicate' | 'failed' }>;
+}
+export interface LinearDailyProgressDeps {
+  version?: string;
+  checklist?: Checklist;
+  history?: (id: string) => ChecklistHistory[];
+  decisions?: DecisionEntry[];
+  now?: Date;
+  apiKey?: string;
+  getSecret?: (id: string) => Promise<string | undefined>;
+  fetch?: typeof fetch;
+  stateDir?: string;
+  dryRun?: boolean;
+  log?: typeof debug.log;
+}
+
+function refsIn(...values: unknown[]): string[] {
+  const found = new Set<string>();
+  for (const value of values) {
+    const text = typeof value === 'string' ? value : value == null ? '' : JSON.stringify(value);
+    for (const match of text.matchAll(ISSUE_REF)) found.add(match[0]);
+  }
+  return [...found];
+}
+
+function cleanTitle(value: string): string {
+  return value.replace(/[\r\n\t]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 180);
+}
+
+function prLinks(value: unknown): string[] {
+  if (typeof value !== 'string') return [];
+  return [...new Set(value.match(/https:\/\/github\.com\/[^\s)]+\/pull\/\d+|\bPR\s*#\d+\b/gi) ?? [])];
+}
+
+/** Build public-safe daily summaries from checklist and decision ledgers. Bodies contain titles, states and links only. */
+export function buildLinearDailyProgressSummaries({ checklist, history = checklistHistory, decisions, now = new Date() }: {
+  checklist?: Checklist; history?: (id: string) => ChecklistHistory[]; decisions: DecisionEntry[]; now?: Date;
+}): LinearDailyProgressSummary[] {
+  if (!checklist) throw new Error('checklist snapshot is required');
+  if (!Number.isFinite(now.getTime())) throw new Error('valid summary date is required');
+  const day = now.toISOString().slice(0, 10);
+  const start = Date.parse(`${day}T00:00:00.000Z`);
+  const end = start + 86_400_000;
+  const issueIds = new Set<string>();
+  const itemRefs = new Map<string, Set<string>>();
+  const changed = new Map<string, ChecklistHistory[]>();
+  for (const item of checklist.items) {
+    const events = history(item.id);
+    const refs = new Set(refsIn(item.id, item.title, item.evidence, item.refs, ...events.flatMap(event => [event.from, event.to])));
+    itemRefs.set(item.id, refs);
+    refs.forEach(id => issueIds.add(id));
+    const today = events.filter(event => {
+      const at = Date.parse(event.at);
+      return Number.isFinite(at) && at >= start && at < end && ['status', 'evidence', 'title', 'move'].includes(event.field);
+    });
+    if (today.length) changed.set(item.id, today);
+  }
+  const decisionRefs = new Map<string, string[]>();
+  for (const decision of decisions) {
+    const refs = refsIn(decision.refs);
+    decisionRefs.set(decision.id, refs);
+    refs.forEach(id => issueIds.add(id));
+  }
+  const summaries: LinearDailyProgressSummary[] = [];
+  for (const identifier of [...issueIds].sort()) {
+    const lines = [`elanous 진행 요약 · ${day}`];
+    const changes: string[] = [];
+    for (const item of checklist.items) {
+      if (!itemRefs.get(item.id)?.has(identifier)) continue;
+      const events = changed.get(item.id) ?? [];
+      if (!events.length) continue;
+      const status = events.filter(event => event.field === 'status').at(-1);
+      const value = status ? `${String(status.from ?? '미상')} → ${String(status.to ?? '미상')}`
+        : events.some(event => event.field === 'evidence') ? '근거 갱신'
+          : events.some(event => event.field === 'title') ? '제목 변경' : '칸 이동';
+      changes.push(`- 칸 ${item.id}: ${cleanTitle(item.title)} · ${value}`);
+      const landedToday = events.some(event => event.field === 'status' && (event.to === 'green' || event.to === 'done'));
+      for (const event of events.filter(event => event.field === 'evidence' && landedToday)) {
+        for (const link of prLinks(event.to)) changes.push(`  착지 PR: ${link}`);
+      }
+    }
+    lines.push('칸 변화');
+    lines.push(...(changes.length ? [...new Set(changes)] : ['- 오늘 기록된 칸 변화 없음']));
+    const issueDecisions = decisions.filter(decision => decisionRefs.get(decision.id)?.includes(identifier) &&
+      (decision.history.some(event => event.at && Date.parse(event.at) >= start && Date.parse(event.at) < end) ||
+        (decision.decidedAt && Date.parse(decision.decidedAt) >= start && Date.parse(decision.decidedAt) < end)));
+    lines.push('결정');
+    lines.push(...(issueDecisions.length ? issueDecisions.map(decision => `- ${cleanTitle(decision.title)} · ${decision.status}`) : ['- 오늘 기록된 결정 없음']));
+    const next = checklist.items.filter(item => item.status !== 'green' && item.status !== 'done' && itemRefs.get(item.id)?.has(identifier));
+    lines.push('다음 할 일');
+    lines.push(...(next.length ? next.slice(0, 8).map(item => `- ${item.id}: ${cleanTitle(item.title)}`) : ['- 연결된 미완료 칸 없음']));
+    const content = lines.join('\n');
+    const contentHash = createHash('sha256').update(content).digest('hex');
+    summaries.push({ identifier, day, body: `${content}\n\n${BODY_MARKER}${day} -->`, contentHash });
+  }
+  return summaries;
+}
+
+async function findIssueAndDuplicate({ apiKey, identifier, day, body, fetch: fetchFn }: { apiKey: string; identifier: string; day: string; body: string; fetch: typeof fetch }): Promise<{ issueId: string; duplicate: boolean }> {
+  // Linear's GraphQL quickstart explicitly queries issue(id: "BLA-123"): https://linear.app/developers/graphql
+  const query = `query DailyProgressIssue($identifier: String!, $after: String) {
+    issue(id: $identifier) { id comments(first: 100, after: $after) { nodes { body } pageInfo { hasNextPage endCursor } } }
+  }`;
+  let after: string | null = null;
+  const cursors = new Set<string>();
+  let issueId: string | undefined;
+  let duplicate = false;
+  do {
+    let response: Response;
+    try {
+      response = await fetchFn('https://api.linear.app/graphql', { method: 'POST', headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query, variables: { identifier, after } }) });
+    } catch { throw new Error('linear-request-failed'); }
+    if (!response.ok) throw new Error(`linear-http-${response.status}`);
+    let result: { data?: { issue?: { id?: string; comments?: { nodes?: Array<{ body?: string }>; pageInfo?: { hasNextPage?: boolean; endCursor?: string | null } } | null } }; errors?: unknown[] };
+    try { result = await response.json() as typeof result; } catch { throw new Error('linear-invalid-json'); }
+    if (result.errors?.length || !result.data?.issue?.id) throw new Error('linear-issue-not-found-or-query-failed');
+    issueId = result.data.issue.id;
+    const comments = result.data.issue.comments;
+    if (comments?.nodes?.some(comment => comment.body?.includes(`${BODY_MARKER}${day} -->`))) duplicate = true;
+    const page = comments?.pageInfo;
+    if (page?.hasNextPage && (!page.endCursor || cursors.has(page.endCursor))) throw new Error('linear-comment-pagination-invalid');
+    after = page?.hasNextPage ? page.endCursor! : null;
+    if (after) cursors.add(after);
+  } while (after && !duplicate);
+  return { issueId, duplicate };
+}
+
+function withDailyLock<T>(stateDir: string, fn: () => Promise<T>): Promise<T> {
+  const path = join(stateDir, 'linear-daily-progress', 'send.lock');
+  mkdirSync(dirname(path), { recursive: true });
+  const deadline = Date.now() + 30_000;
+  let fd: number | undefined;
+  for (;;) {
+    try {
+      fd = openSync(path, 'wx', 0o600);
+      try { writeSync(fd, `${process.pid}`); }
+      catch (error) { closeSync(fd); fd = undefined; unlinkSync(path); throw error; }
+      break;
+    }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      try {
+        const pid = Number(readFileSync(path, 'utf8'));
+        if (Number.isSafeInteger(pid) && pid > 0 && Date.now() - statSync(path).mtimeMs > 30_000) {
+          try { process.kill(pid, 0); } catch (inner) { if ((inner as NodeJS.ErrnoException).code === 'ESRCH') { unlinkSync(path); continue; } }
+        }
+      } catch (inner) { if ((inner as NodeJS.ErrnoException).code === 'ENOENT') continue; }
+      if (Date.now() >= deadline) throw new Error('linear daily progress lock timeout');
+      Atomics.wait(WAIT, 0, 0, 25);
+    }
+  }
+  return fn().finally(() => {
+    if (fd === undefined) return;
+    try { closeSync(fd); }
+    finally {
+      try { unlinkSync(path); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    }
+  });
+}
+
+/** Dry-run by default at the CLI; live delivery checks Linear first so a retry after a crash cannot duplicate a comment. */
+export async function syncLinearDailyProgress(deps: LinearDailyProgressDeps = {}): Promise<LinearDailyProgressResult> {
+  const checklist = deps.checklist ?? listChecklist(deps.version ?? checklistDevVersion());
+  const decisions = deps.decisions ?? new DecisionLedger({ stateDir: deps.stateDir }).list({ status: 'all' });
+  const summaries = buildLinearDailyProgressSummaries({ checklist, history: deps.history ?? checklistHistory, decisions, now: deps.now });
+  const result: LinearDailyProgressResult = { posted: 0, skipped: 0, failed: 0, dryRun: deps.dryRun !== false, plan: [] };
+  if (!summaries.length) return result;
+  const log = deps.log ?? debug.log.bind(debug);
+  const stateDir = deps.stateDir ?? elanousStateRoot();
+  if (result.dryRun) {
+    result.plan = summaries.map(({ identifier, day, contentHash, body }) => ({ identifier, day, contentHash, body, status: 'dry-run' }));
+    return result;
+  }
+  const apiKey = deps.apiKey ?? await (deps.getSecret ?? getSecretAsync)('connector.linear.apiKey');
+  if (!apiKey) throw new Error('connector.linear.apiKey missing');
+  return withDailyLock(stateDir, async () => {
+    for (const summary of summaries) {
+      const fields = { traceId: randomUUID(), identifier: summary.identifier, day: summary.day, contentHash: summary.contentHash };
+      try {
+        const issue = await findIssueAndDuplicate({ apiKey, identifier: summary.identifier, day: summary.day, body: summary.body, fetch: deps.fetch ?? fetch });
+        if (issue.duplicate) {
+          result.skipped++;
+          result.plan.push({ identifier: summary.identifier, day: summary.day, contentHash: summary.contentHash, body: summary.body, status: 'duplicate' });
+          log('connector.linear.daily-progress', 'skipped', { ...fields, reason: 'duplicate-content' });
+          continue;
+        }
+        await commentLinearIssue({ apiKey, issueId: issue.issueId, body: summary.body, fetch: deps.fetch ?? fetch });
+        result.posted++;
+        result.plan.push({ identifier: summary.identifier, day: summary.day, contentHash: summary.contentHash, body: summary.body, status: 'posted' });
+        log('connector.linear.daily-progress', 'posted', fields);
+      } catch (error) {
+        result.failed++;
+        result.plan.push({ identifier: summary.identifier, day: summary.day, contentHash: summary.contentHash, body: summary.body, status: 'failed' });
+        const reason = error instanceof Error && /^linear-(?:request-failed|http-\d{3}|invalid-json|issue-not-found-or-query-failed|comment-pagination-invalid)$/.test(error.message)
+          ? error.message : 'linear-operation-failed';
+        log('connector.linear.daily-progress', 'failed', { ...fields, reason });
+      }
+    }
+    return result;
+  });
+}

package/src/connectors/linear-projector.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import type { Task, TaskExecution, TaskStatus } from '../task-orchestrator/types.js';
 import { EventLedger } from './event-ledger.js';
+import { parseLinearSecretaryManifest, readApprovedLinearCapture, updateLinearSecretaryProgress } from '../intake-plane/linear-wish.js';
 
 const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
 const STATE_NAMES: Partial<Record<TaskStatus, string>> = {
@@ -10,7 +11,7 @@ const STATE_NAMES: Partial<Record<TaskStatus, string>> = {
   failed: 'Todo',
 };
 
-type ProjectableTask = Pick<Task, 'id' | 'status' | 'generatedBy' | 'lastExecutionId' | 'notes'>;
+type ProjectableTask = Pick<Task, 'id' | 'status' | 'generatedBy' | 'lastExecutionId' | 'notes'> & Pick<Partial<Task>, 'description' | 'title'>;
 
 export interface LinearProjectionOptions {
   task: ProjectableTask;
@@ -19,7 +20,7 @@ export interface LinearProjectionOptions {
   ledger?: EventLedger;
   /** Linear user ID for the elanous agent, when configured. */
   assigneeId?: string;
-  execution?: Pick<TaskExecution, 'output' | 'error'>;
+  execution?: Pick<TaskExecution, 'output' | 'error' | 'runId' | 'captureArtifacts'>;
 }
 
 async function graphql<T>(apiKey: string, fetchFn: typeof fetch, query: string, variables: Record<string, unknown>): Promise<T> {
@@ -34,25 +35,46 @@ async function graphql<T>(apiKey: string, fetchFn: typeof fetch, query: string,
   return result.data;
 }
 
-function projectionComment(task: ProjectableTask, execution?: LinearProjectionOptions['execution']): string | null {
+function projectionComment(task: ProjectableTask): string | null {
   switch (task.status) {
     case 'running': return `elanous 실행 시작 (task: ${task.id}${task.lastExecutionId ? `, execution: ${task.lastExecutionId}` : ''}).`;
-    case 'review': return `elanous 실행 결과가 사람 확인을 기다립니다 (task: ${task.id}).${execution?.output ? `\n\n${execution.output.slice(0, 2000)}` : ''}`;
-    case 'done': return `elanous 실행 완료 (task: ${task.id}).${execution?.output ? `\n\n${execution.output.slice(0, 2000)}` : ''}`;
-    case 'failed': {
-      const reason = execution?.error?.message ?? task.notes.at(-1);
-      return `elanous 실행 실패 (task: ${task.id}).${reason ? `\n\n${reason.slice(0, 2000)}` : ''}`;
-    }
+    case 'review': return `elanous 실행 결과가 사람 확인을 기다립니다 (task: ${task.id}).`;
+    case 'done': return `elanous 실행 완료 (task: ${task.id}).`;
+    case 'failed': return `elanous 실행 실패 (task: ${task.id}).`;
     default: return null;
   }
 }
 
 /** Project only Linear-origin task transitions. Every successful write is recorded for inbound echo filtering. */
 export async function projectLinearTask({ task, apiKey, fetch: fetchFn = fetch, ledger, assigneeId, execution }: LinearProjectionOptions): Promise<boolean> {
-  if (task.generatedBy?.kind !== 'external' || task.generatedBy.provider !== 'linear' || !task.generatedBy.ref || !STATE_NAMES[task.status]) return false;
-  if (!apiKey) throw new Error('Linear API key is required for projection');
+  if (task.generatedBy?.kind !== 'external' || task.generatedBy.provider !== 'linear' || !task.generatedBy.ref) return false;
   const issueId = task.generatedBy.ref;
   const events = ledger ?? new EventLedger();
+  const secretary = parseLinearSecretaryManifest(task.description ?? '', issueId);
+  if (secretary) {
+    if (task.status !== 'running' && task.status !== 'review' && task.status !== 'done' && task.status !== 'failed') return false;
+    if (!apiKey) throw new Error('Linear API key is required for projection');
+    const state = task.status === 'running' ? 'started' : task.status === 'done' ? 'completed' : 'comment';
+    const captureCandidate = execution?.captureArtifacts?.find(capture =>
+      capture.runId === execution.runId && capture.runId.trim().length > 0 &&
+      capture.linearIssueId === secretary.parentIssueId && capture.externalShare === true && capture.sensitivity === 'public');
+    let captureArtifact: typeof captureCandidate;
+    if (captureCandidate) {
+      try { readApprovedLinearCapture(captureCandidate); captureArtifact = captureCandidate; }
+      catch { /* Invalid, stale, or unavailable captures fail closed; progress still syncs without a URL. */ }
+    }
+    await updateLinearSecretaryProgress({ apiKey, parentIssueId: secretary.parentIssueId, taskIssueId: issueId,
+      taskTitle: secretary.tasks.find(item => item.issueId === issueId)!.title, tasks: secretary.tasks, state,
+      summary: task.status === 'running' ? '하위 작업을 시작했습니다.'
+        : task.status === 'done' ? '하위 작업을 완료했습니다.'
+          : task.status === 'failed' ? '하위 작업이 실패했습니다.' : '하위 작업 진행 상태를 갱신했습니다.',
+      workaround: task.status === 'failed' ? 'Linear 상태는 In Progress로 유지하고 실패 내용을 기록했습니다.' : undefined,
+      captureArtifact,
+      ledger: events, fetch: fetchFn });
+    return true;
+  }
+  if (!STATE_NAMES[task.status]) return false;
+  if (!apiKey) throw new Error('Linear API key is required for projection');
   const { issue, viewer } = await graphql<{
     issue?: { team?: { states?: { nodes?: Array<{ id: string; name: string }> } } };
     viewer?: { id?: string };
@@ -72,7 +94,7 @@ export async function projectLinearTask({ task, apiKey, fetch: fetchFn = fetch,
   events.record('linear', `outgoing:state:${issueId}:${update.issueUpdate.issue.updatedAt}:${stateHash}`,
     { ref: issueId, occurredAt: update.issueUpdate.issue.updatedAt });
 
-  const comment = projectionComment(task, execution);
+  const comment = projectionComment(task);
   if (comment) {
     const created = await graphql<{ commentCreate?: { success?: boolean; comment?: { id?: string; updatedAt?: string; issue?: { updatedAt?: string } } } }>(apiKey, fetchFn,
       'mutation ProjectorComment($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id updatedAt issue { updatedAt } } } }',

package/src/connectors/linear.ts

@@ -180,6 +180,12 @@ export async function resolveLinearProjectId({ apiKey, project, fetch: fetchFn =
   return projectId;
 }
 
+export async function resolveLinearViewerId({ apiKey, fetch: fetchFn = fetch }: LinearRequestOptions): Promise<string> {
+  const data = await linearRequest<{ viewer?: { id?: string } }>({ apiKey, fetch: fetchFn }, 'query LinearSecretaryViewer { viewer { id } }', {});
+  if (!data.viewer?.id) throw new Error('Linear viewer id could not be resolved');
+  return data.viewer.id;
+}
+
 /** Read-only project lookup. A name is resolved uniquely before querying its issues. */
 export async function fetchLinearProjectIssues({ apiKey, project, includeDone = false, fetch: fetchFn = fetch }: {
   apiKey: string; project: string; includeDone?: boolean; fetch?: typeof fetch;
@@ -234,17 +240,47 @@ export async function findLinearDecisionIssue({ apiKey, projectId, decisionId, f
   return match;
 }
 
-/** Create in the COO project; Linear requires a team from that project for issueCreate. */
-export async function createLinearIssue({ apiKey, projectId, title, description, dueDate, fetch: fetchFn = fetch }: LinearRequestOptions & {
-  projectId: string; title: string; description: string; dueDate?: string;
+/** Create in a project or directly in an explicitly selected team. */
+export async function createLinearIssue({ apiKey, projectId, teamKey, title, description, dueDate, parentId, assigneeId, stateType, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  projectId?: string; teamKey?: string; title: string; description: string; dueDate?: string; parentId?: string; assigneeId?: string;
+  stateType?: 'started' | 'unstarted' | 'completed' | 'canceled';
 }): Promise<string> {
-  const data = await linearRequest<{ project?: { teams?: { nodes?: Array<{ id: string }> } } }>({ apiKey, fetch: fetchFn },
-    'query DecisionProjectTeam($id: String!) { project(id: $id) { teams { nodes { id } } } }', { id: projectId });
+  if (!apiKey.trim() || (!projectId?.trim() && !teamKey?.trim())) throw new Error('Linear project or team and API key are required');
+  if (!projectId?.trim()) return createLinearTeamIssue({ apiKey, teamKey: teamKey!.trim(), title, description, dueDate, parentId, assigneeId, stateType, fetch: fetchFn });
+  type Team = { id: string; states?: { nodes?: Array<{ id: string; type: string }> } };
+  const data = await linearRequest<{ project?: { teams?: { nodes?: Team[] } } }>({ apiKey, fetch: fetchFn },
+    'query DecisionProjectTeam($id: String!) { project(id: $id) { teams { nodes { id states { nodes { id type } } } } } }', { id: projectId });
   const teams = data.project?.teams?.nodes;
   if (!teams?.[0]?.id) throw new Error('Linear project has no team');
+  const stateId = stateType ? teams[0].states?.nodes?.find(state => state.type === stateType)?.id : undefined;
+  if (stateType && !stateId) throw new Error(`Linear team workflow state not found: ${stateType}`);
   const created = await linearRequest<{ issueCreate?: { success?: boolean; issue?: { id?: string } } }>({ apiKey, fetch: fetchFn },
     'mutation DecisionIssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id } } }',
-    { input: { teamId: teams[0].id, projectId, title, description, ...(dueDate ? { dueDate } : {}) } });
+    { input: {
+      teamId: teams[0].id, projectId, title, description,
+      ...(dueDate ? { dueDate } : {}), ...(parentId ? { parentId } : {}), ...(assigneeId ? { assigneeId } : {}), ...(stateId ? { stateId } : {}),
+    } });
+  const id = created.issueCreate?.issue?.id;
+  if (!created.issueCreate?.success || !id) throw new Error('Linear issueCreate did not return an issue id');
+  return id;
+}
+
+/** Create an issue directly in a team, without requiring a project. */
+export async function createLinearTeamIssue({ apiKey, teamKey, title, description, dueDate, parentId, assigneeId, stateType, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  teamKey: string; title: string; description?: string; dueDate?: string; parentId?: string; assigneeId?: string;
+  stateType?: 'started' | 'unstarted' | 'completed' | 'canceled';
+}): Promise<string> {
+  if (!apiKey.trim() || !teamKey.trim() || !title.trim()) throw new Error('Linear team, title and API key are required');
+  const data = await linearRequest<{ teams?: { nodes?: Array<{ id?: string; states?: { nodes?: Array<{ id: string; type: string }> } }> } }>({ apiKey, fetch: fetchFn },
+    'query LinearTeamByKey($key: String!) { teams(filter: { key: { eq: $key } }) { nodes { id states { nodes { id type } } } } }', { key: teamKey.trim() });
+  const teams = data.teams?.nodes ?? [];
+  if (teams.length !== 1 || !teams[0]?.id) throw new Error(teams.length ? 'Linear team key is ambiguous' : 'Linear team key was not found');
+  const stateId = stateType ? teams[0].states?.nodes?.find(state => state.type === stateType)?.id : undefined;
+  if (stateType && !stateId) throw new Error(`Linear team workflow state not found: ${stateType}`);
+  const created = await linearRequest<{ issueCreate?: { success?: boolean; issue?: { id?: string } } }>({ apiKey, fetch: fetchFn },
+    'mutation LinearTeamIssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id } } }',
+    { input: { teamId: teams[0].id, title: title.trim(), ...(description?.trim() ? { description: description.trim() } : {}),
+      ...(dueDate ? { dueDate } : {}), ...(parentId ? { parentId } : {}), ...(assigneeId ? { assigneeId } : {}), ...(stateId ? { stateId } : {}) } });
   const id = created.issueCreate?.issue?.id;
   if (!created.issueCreate?.success || !id) throw new Error('Linear issueCreate did not return an issue id');
   return id;
@@ -257,8 +293,74 @@ export async function commentLinearIssue({ apiKey, issueId, body, fetch: fetchFn
   if (!data.commentCreate?.success || !data.commentCreate.comment?.id) throw new Error('Linear commentCreate failed');
 }
 
+export async function createLinearAttachment({ apiKey, issueId, title, url, subtitle, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  issueId: string; title: string; url: string; subtitle?: string;
+}): Promise<string> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:') throw new Error('Linear attachment URL must use HTTPS');
+  const data = await linearRequest<{ attachmentCreate?: { success?: boolean; attachment?: { id?: string } } }>({ apiKey, fetch: fetchFn },
+    'mutation LinearAttachmentCreate($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success attachment { id } } }',
+    { input: { issueId, title, url: parsed.toString(), ...(subtitle ? { subtitle } : {}) } });
+  const id = data.attachmentCreate?.attachment?.id;
+  if (!data.attachmentCreate?.success || !id) throw new Error('Linear attachmentCreate did not return an attachment id');
+  return id;
+}
+
+/** Request a signed Linear upload URL and stream a generated artifact from the server. */
+export async function uploadLinearFile({ apiKey, filename, contentType, body, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  filename: string; contentType: string; body: Buffer;
+}): Promise<string> {
+  const data = await linearRequest<{ fileUpload?: { success?: boolean; uploadFile?: {
+    uploadUrl?: string; assetUrl?: string; headers?: Array<{ key: string; value: string }>;
+  } } }>({ apiKey, fetch: fetchFn },
+    `mutation LinearFileUpload($contentType: String!, $filename: String!, $size: Int!) {
+      fileUpload(contentType: $contentType, filename: $filename, size: $size) {
+        success uploadFile { uploadUrl assetUrl headers { key value } }
+      }
+    }`,
+    { contentType, filename, size: body.byteLength });
+  const upload = data.fileUpload?.uploadFile;
+  if (!data.fileUpload?.success || !upload?.uploadUrl || !upload.assetUrl || !Array.isArray(upload.headers)) {
+    throw new Error('Linear fileUpload did not return an upload URL');
+  }
+  const uploadUrl = new URL(upload.uploadUrl);
+  const assetUrl = new URL(upload.assetUrl);
+  if (uploadUrl.protocol !== 'https:' || assetUrl.protocol !== 'https:') throw new Error('Linear file upload URLs must use HTTPS');
+  const headers = new Headers({ 'Content-Type': contentType, 'Cache-Control': 'public, max-age=31536000' });
+  for (const header of upload.headers) {
+    if (!header || typeof header.key !== 'string' || typeof header.value !== 'string') throw new Error('Linear fileUpload returned invalid headers');
+    headers.set(header.key, header.value);
+  }
+  let response: Response;
+  try {
+    const uploadBody = new Uint8Array(body.byteLength);
+    uploadBody.set(body);
+    response = await fetchFn(uploadUrl, { method: 'PUT', headers, body: uploadBody, redirect: 'error' });
+  } catch {
+    throw new Error('Linear file upload PUT failed');
+  }
+  if (!response.ok) throw new Error(`Linear file upload PUT HTTP ${response.status}`);
+  return assetUrl.toString();
+}
+
+export async function updateLinearIssueDescription({ apiKey, issueId, description, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  issueId: string; description: string;
+}): Promise<void> {
+  const data = await linearRequest<{ issueUpdate?: { success?: boolean } }>({ apiKey, fetch: fetchFn },
+    'mutation LinearIssueDescriptionUpdate($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }',
+    { id: issueId, input: { description } });
+  if (!data.issueUpdate?.success) throw new Error('Linear issue description update failed');
+}
+
+export async function fetchLinearIssueDescription({ apiKey, issueId, fetch: fetchFn = fetch }: LinearRequestOptions & { issueId: string }): Promise<string> {
+  const data = await linearRequest<{ issue?: { description?: string | null } }>({ apiKey, fetch: fetchFn },
+    'query LinearIssueDescription($id: String!) { issue(id: $id) { description } }', { id: issueId });
+  if (typeof data.issue?.description !== 'string') throw new Error('Linear issue description is missing');
+  return data.issue.description;
+}
+
 export async function moveLinearIssueToStateType({ apiKey, issueId, type, fetch: fetchFn = fetch }: LinearRequestOptions & {
-  issueId: string; type: 'completed' | 'canceled';
+  issueId: string; type: 'unstarted' | 'started' | 'completed' | 'canceled';
 }): Promise<void> {
   const data = await linearRequest<{ issue?: { team?: { states?: { nodes?: Array<{ id: string; type: string }> } } } }>({ apiKey, fetch: fetchFn },
     'query DecisionIssueStates($id: String!) { issue(id: $id) { team { states { nodes { id type } } } } }', { id: issueId });
@@ -270,6 +372,48 @@ export async function moveLinearIssueToStateType({ apiKey, issueId, type, fetch:
   if (!updated.issueUpdate?.success) throw new Error('Linear issueUpdate failed');
 }
 
+/** Check the issue's current workflow state and transition in one fresh read/write operation. */
+export async function transitionLinearIssueStateType({ apiKey, issueId, type, fromTypes, fetch: fetchFn = fetch }: LinearRequestOptions & {
+  issueId: string; type: 'unstarted' | 'started' | 'completed' | 'canceled'; fromTypes?: readonly string[];
+}): Promise<boolean> {
+  const data = await linearRequest<{ issue?: { state?: { type?: string } | null; team?: { states?: { nodes?: Array<{ id: string; type: string }> } } } }>({ apiKey, fetch: fetchFn },
+    'query LinearIssueTransitionGuard($id: String!) { issue(id: $id) { state { type } team { states { nodes { id type } } } } }', { id: issueId });
+  const currentType = data.issue?.state?.type;
+  if (!currentType || currentType === 'completed' || currentType === 'canceled' || (fromTypes && !fromTypes.includes(currentType))) return false;
+  const state = data.issue?.team?.states?.nodes?.find(node => node.type === type);
+  if (!state?.id) throw new Error(`Linear team workflow state not found: ${type}`);
+  const updated = await linearRequest<{ issueUpdate?: { success?: boolean } }>({ apiKey, fetch: fetchFn },
+    'mutation LinearIssueTransition($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }',
+    { id: issueId, input: { stateId: state.id } });
+  if (!updated.issueUpdate?.success) throw new Error('Linear issueUpdate failed');
+  return true;
+}
+
+export async function fetchLinearIssueStateType({ apiKey, issueId, fetch: fetchFn = fetch }: LinearRequestOptions & { issueId: string }): Promise<string> {
+  const data = await linearRequest<{ issue?: { state?: { type?: string } | null } }>({ apiKey, fetch: fetchFn },
+    'query LinearIssueStatus($id: String!) { issue(id: $id) { state { type } } }', { id: issueId });
+  const type = data.issue?.state?.type;
+  if (!type) throw new Error('Linear issue state type is missing');
+  return type;
+}
+
+/** Read the immutable identity needed to bind a demo mission to a real child issue. */
+export async function fetchLinearMissionIssueIdentity({ apiKey, issueId, fetch: fetchFn = fetch }: LinearRequestOptions & { issueId: string }): Promise<{ id: string; teamKey: string; parentId: string | null }> {
+  const data = await linearRequest<{ issue?: { id?: string; team?: { key?: string } | null; parent?: { id?: string } | null } }>({ apiKey, fetch: fetchFn },
+    'query LinearMissionIssueIdentity($id: String!) { issue(id: $id) { id team { key } parent { id } } }', { id: issueId });
+  const issue = data.issue;
+  if (!issue?.id || !issue.team?.key) throw new Error('Linear issue identity is incomplete');
+  return { id: issue.id, teamKey: issue.team.key, parentId: issue.parent?.id ?? null };
+}
+
+export async function fetchLinearIssueUpdatedAt({ apiKey, issueId, fetch: fetchFn = fetch }: LinearRequestOptions & { issueId: string }): Promise<string> {
+  const data = await linearRequest<{ issue?: { updatedAt?: string } }>({ apiKey, fetch: fetchFn },
+    'query LinearIssueUpdatedAt($id: String!) { issue(id: $id) { updatedAt } }', { id: issueId });
+  const updatedAt = data.issue?.updatedAt;
+  if (!updatedAt || !Number.isFinite(Date.parse(updatedAt))) throw new Error('Linear issue updatedAt is missing');
+  return updatedAt;
+}
+
 export function toTaskRequest(event: ExternalTaskEvent): {
   title: string; description: string; priority: 'high' | 'medium' | 'low';
   external: { provider: 'linear'; ref: string; url?: string; team?: string };