elanous 0.2.42 → 0.2.44

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 };

package/src/control-plane/ledger.ts

@@ -20,7 +20,7 @@ export interface ResourceRecord {
 export type ResourceView = ResourceRecord & { ageMs: number; expired: boolean };
 
 export interface PodWorkerKey { context: string; imageDigest: string; lockHash: string; architecture: string }
-type PodWorkerState = 'idle' | 'leased' | 'sanitizing' | 'timeout-fenced' | 'quarantined';
+type PodWorkerState = 'idle' | 'leased' | 'sanitizing' | 'timeout-fenced' | 'quarantined' | 'reaping';
 interface PodWorkerLeaseAttrs {
   key: PodWorkerKey;
   podUid: string;
@@ -35,6 +35,8 @@ interface PodWorkerLeaseAttrs {
   timeoutFenceUntil?: number;
   timeoutRunId?: string;
   timeoutAttemptId?: string;
+  timeoutPreviousObservedAt?: number;
+  timeoutPreviousTtlMs?: number;
   runId?: string;
   attemptId?: string;
   reason?: string;
@@ -216,6 +218,13 @@ export class ResourceLedger {
     now ??= Date.now();
     const rows = this.read();
     const id = `pod-worker-lease:${request.workerId}`;
+    if (rows.some(row => {
+      if (row.kind !== 'pod-worker-lease' || row.name === request.workerId) return false;
+      const attrs = workerAttrs(row);
+      return attrs.podUid === request.podUid
+        && (attrs.state === 'quarantined' || attrs.state === 'timeout-fenced' || attrs.state === 'reaping');
+    }))
+      throw new ResourceLedgerError(409, 'pod-uid-already-registered');
     const index = rows.findIndex(row => row.id === id);
     const previous = index < 0 ? undefined : rows[index]!;
     if (previous && previous.kind !== 'pod-worker-lease') throw new ResourceLedgerError(409, 'worker-id-conflict');
@@ -244,8 +253,10 @@ export class ResourceLedger {
       const idleAttrs: PodWorkerLeaseAttrs = { ...candidateAttrs, state: 'idle' };
       delete idleAttrs.leaseId; delete idleAttrs.leaseOwner; delete idleAttrs.runId; delete idleAttrs.attemptId;
       delete idleAttrs.timeoutFenceUntil; delete idleAttrs.timeoutRunId; delete idleAttrs.timeoutAttemptId;
-      rows[rowIndex] = { ...candidate, attrs: idleAttrs as unknown as Record<string, unknown>, observedAt: at,
-        ttlMs: candidateAttrs.idleTtlMs };
+      const observedAt = candidateAttrs.timeoutPreviousObservedAt ?? at;
+      const ttlMs = candidateAttrs.timeoutPreviousTtlMs ?? candidateAttrs.idleTtlMs;
+      delete idleAttrs.timeoutPreviousObservedAt; delete idleAttrs.timeoutPreviousTtlMs;
+      rows[rowIndex] = { ...candidate, attrs: idleAttrs as unknown as Record<string, unknown>, observedAt, ttlMs };
       expiredFenceChanged = true;
     }
     const index = rows.findIndex(row => row.kind === 'pod-worker-lease' && (!request.machine || row.machine === request.machine)
@@ -283,12 +294,16 @@ export class ResourceLedger {
         && attrs.timeoutAttemptId === request.attemptId;
       const sameLease = attrs.state === 'leased' && attrs.leaseOwner === request.owner
         && attrs.runId === request.runId && attrs.attemptId === request.attemptId;
-      const available = attrs.state === 'idle';
+      const available = attrs.state === 'idle' && Math.max(0, at - row.observedAt) < row.ttlMs;
       if (!request.owner || !request.runId || !request.attemptId || !Number.isSafeInteger(request.fenceMs)
         || request.fenceMs < 1 || !(sameFence || sameLease || available))
         throw new ResourceLedgerError(409, 'stale-timeout-fence');
       const nextAttrs: PodWorkerLeaseAttrs = { ...attrs, state: 'timeout-fenced',
         timeoutFenceUntil: at + request.fenceMs, timeoutRunId: request.runId, timeoutAttemptId: request.attemptId };
+      if (available) {
+        nextAttrs.timeoutPreviousObservedAt = row.observedAt;
+        nextAttrs.timeoutPreviousTtlMs = row.ttlMs;
+      }
       const next: ResourceRecord = { ...row, attrs: nextAttrs as unknown as Record<string, unknown>, observedAt: at };
       rows[index] = next;
       this.write(rows);
@@ -296,6 +311,29 @@ export class ResourceLedger {
     });
   }
 
+  /** Atomically reserves a fenced Pod UID so a timeout-fence expiry cannot make it leasable during deletion. */
+  reservePodWorkerReap(id: string, request: { machine: string; podUid: string }, now?: number): ResourceRecord {
+    return this.mutate(() => {
+      now ??= Date.now();
+      const rows = this.read();
+      const index = rows.findIndex(row => row.id === id && row.kind === 'pod-worker-lease');
+      if (index < 0) throw new ResourceLedgerError(404, 'not-found');
+      const row = rows[index]!;
+      const attrs = workerAttrs(row);
+      if (row.machine !== request.machine || attrs.podUid !== request.podUid || attrs.leaseId
+        || !['quarantined', 'timeout-fenced', 'reaping'].includes(attrs.state))
+        throw new ResourceLedgerError(409, 'pod-worker-reap-not-eligible');
+      if (rows.some((other, otherIndex) => otherIndex !== index && other.kind === 'pod-worker-lease'
+        && workerAttrs(other).podUid === request.podUid))
+        throw new ResourceLedgerError(409, 'pod-worker-uid-has-other-lease');
+      const next: ResourceRecord = { ...row,
+        attrs: { ...attrs, state: 'reaping' } as unknown as Record<string, unknown>, observedAt: now };
+      rows[index] = next;
+      this.write(rows);
+      return next;
+    });
+  }
+
   transitionPodWorker(id: string, request: { owner: string; leaseId: string; generation: number; action: 'renew' | 'release' | 'sanitize' | 'quarantine'; ttlMs?: number; reason?: string }, now?: number): ResourceRecord {
     return this.mutate(() => {
     now ??= Date.now();

package/src/control-plane/member-tokens.ts

@@ -1,6 +1,6 @@
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
-import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, fsyncSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 
 interface MemberTokenEntry { sha256: string; issuedAt: string }
@@ -65,6 +65,29 @@ export function issueMemberToken(machine: string, root: string = effectiveInstan
   return token;
 }
 
+/** Issue a member credential into a new private file without sending the value to stdout. */
+export function issueMemberTokenToFile(machine: string, tokenFile: string, root: string = effectiveInstanceRoot()): void {
+  checkMachine(machine);
+  if (!isAbsolute(tokenFile)) throw new Error('token file path must be absolute');
+  const token = randomBytes(32).toString('hex');
+  mkdirSync(dirname(tokenFile), { recursive: true, mode: 0o700 });
+  let outputCreated = false;
+  try {
+    const fd = openSync(tokenFile, 'wx', 0o600);
+    outputCreated = true;
+    try {
+      writeFileSync(fd, `${token}\n`, 'utf8');
+      fsyncSync(fd);
+    } finally { closeSync(fd); }
+    const entries = readStore(root);
+    entries[machine] = { sha256: createHash('sha256').update(token).digest('hex'), issuedAt: new Date().toISOString() };
+    writeStore(root, entries);
+  } catch (error) {
+    if (outputCreated) try { unlinkSync(tokenFile); } catch { /* retain the original failure */ }
+    throw error;
+  }
+}
+
 export function revokeMemberToken(machine: string, root: string = effectiveInstanceRoot()): void {
   checkMachine(machine);
   const entries = readStore(root);

package/src/control-plane/ports.ts

@@ -1,9 +1,12 @@
 import { ResourceLedger, ResourceLedgerError, type ResourceRecord } from './ledger.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
 
-/** Inclusive port bands; only the test band is allocated by the coordinator. */
+/** Release PWA bind configured by OP; isolated test leases must never claim it. */
+export const RELEASE_PWA_FIXED_HTTP_PORT = 31453;
+
+/** Inclusive port bands. Fixed release PWA ports are reserved from every isolated test allocator. */
 export const PORT_BANDS = {
-  reserved: [31413, DEFAULT_NEXUS_HTTP_PORT, 31420],
+  reserved: [31413, DEFAULT_NEXUS_HTTP_PORT, 31420, RELEASE_PWA_FIXED_HTTP_PORT],
   test: { start: 31450, end: 31499 },
   offline: { start: 31500, end: 31509 },
 } as const;
@@ -36,5 +39,7 @@ export function leasePort(request: PortLeaseRequest, ledger: ResourceLedger, now
     throw new ResourceLedgerError(400, 'invalid-port-lease');
   }
   const owner = request.owner ?? machine;
-  return ledger.leaseTestPort({ machine, purpose, ttlMs: Math.min(ttlMs, MAX_PORT_LEASE_TTL_MS), owner }, PORT_BANDS.test, now, request.excluded);
+  const reservedTestPorts = PORT_BANDS.reserved.filter(port => port >= PORT_BANDS.test.start && port <= PORT_BANDS.test.end);
+  const excluded = [...new Set([...(request.excluded ?? []), ...reservedTestPorts])];
+  return ledger.leaseTestPort({ machine, purpose, ttlMs: Math.min(ttlMs, MAX_PORT_LEASE_TTL_MS), owner }, PORT_BANDS.test, now, excluded);
 }

package/src/control-plane/server.ts

@@ -12,12 +12,17 @@ export const CONTROL_HOSTNAME = '127.0.0.1';
 const MAX_POD_WORKER_TTL_MS = 24 * 60 * 60 * 1000;
 const POD_WORKER_TIMEOUT_FENCE_MS = 150_000;
 
-export function allowedControlHostname(hostname: string): boolean {
+function controlHostnameAllowed(hostname: string, allowClusterBind: boolean): boolean {
+  // Cluster-facing binds require an explicit opt-in; wildcard exposure is never inferred from the address.
+  if (hostname === '0.0.0.0') return allowClusterBind;
   if (hostname === '127.0.0.1' || hostname === '::1') return true;
   const parts = hostname.split('.');
   if (parts.length !== 4 || !parts.every(part => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255)) return false;
   return parts[0] === '100' && Number(parts[1]) >= 64 && Number(parts[1]) <= 127;
 }
+export function allowedControlHostname(hostname: string): boolean {
+  return controlHostnameAllowed(hostname, false);
+}
 export type ControlScope = 'admin' | 'member' | 'query';
 export type ControlTokens = Record<ControlScope, string>;
 
@@ -89,6 +94,7 @@ export interface ControlServerOptions {
   root?: string;
   port?: number;
   hostname?: string;
+  allowClusterBind?: boolean;
   leaseView?: LeaseHolderView;
   requireKnownLeaseForWrites?: boolean;
 }
@@ -99,7 +105,7 @@ export function startControlServer(opts: ControlServerOptions = {}): {
   stop(): void;
 } {
   const hostname = opts.hostname ?? CONTROL_HOSTNAME;
-  if (!allowedControlHostname(hostname)) throw new Error('invalid control hostname');
+  if (!controlHostnameAllowed(hostname, opts.allowClusterBind ?? false)) throw new Error('invalid control hostname');
   const root = opts.root ?? effectiveInstanceRoot();
   const tokens = ensureControlTokens(root);
   const ledger = new ResourceLedger(root);
@@ -127,7 +133,7 @@ export function startControlServer(opts: ControlServerOptions = {}): {
         const leaseRenewal = /^\/v1\/leases\/port\/([^/]+)\/heartbeat$/.exec(path);
         const workerRegister = path === '/v1/workers/pod' && method === 'POST';
         const workerAcquire = path === '/v1/leases/pod-worker' && method === 'POST';
-        const workerTransition = /^\/v1\/leases\/pod-worker\/([^/]+)\/(renew|release|sanitize|quarantine|timeout)$/.exec(path);
+        const workerTransition = /^\/v1\/leases\/pod-worker\/([^/]+)\/(renew|release|sanitize|quarantine|timeout|reap)$/.exec(path);
         if (!resourcePath && !registerPath && !leaseRequest && !workerRegister && !workerAcquire && !(workerTransition && method === 'POST') && !(leaseDeletion && method === 'DELETE') && !(leaseRenewal && method === 'POST') && !(heartbeat && method === 'POST') && !(deletion && method === 'DELETE')) {
           return json({ error: 'not-found' }, 404);
         }
@@ -177,10 +183,13 @@ export function startControlServer(opts: ControlServerOptions = {}): {
               () => ledger.registerPodWorker({ workerId, machine: workerMachine, podUid, key: podWorkerKey(key), ttlMs, owner })));
           }
           if (workerAcquire) {
-            if (scope !== 'member') throw new ResourceLedgerError(403, 'worker-consumer-required');
+            // A host-scoped provider may acquire only its own worker lease. Global consumers
+            // retain the member scope; a machine credential can never select another host.
+            if (scope !== 'member' && !machine) throw new ResourceLedgerError(403, 'worker-consumer-required');
             const body = podWorkerBody(await req.json());
             const { machine: workerMachine, key, runId, attemptId, ttlMs } = body;
             if (workerMachine !== undefined && (typeof workerMachine !== 'string' || !workerMachine.trim())) throw new ResourceLedgerError(400, 'invalid-pod-worker-lease');
+            if (machine && workerMachine !== machine) throw new ResourceLedgerError(403, 'machine-scope');
             if (typeof runId !== 'string' || !runId.trim() || typeof attemptId !== 'string' || !attemptId.trim()
               || typeof ttlMs !== 'number' || !Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > MAX_POD_WORKER_TTL_MS) throw new ResourceLedgerError(400, 'invalid-pod-worker-lease');
             const stale = await currentWorkerPrimary();
@@ -192,7 +201,19 @@ export function startControlServer(opts: ControlServerOptions = {}): {
           if (workerTransition) {
             const workerId = decodeURIComponent(workerTransition[1]!);
             if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$/.test(workerId)) throw new ResourceLedgerError(400, 'invalid-worker-id');
-            const action = workerTransition[2] as 'renew' | 'release' | 'sanitize' | 'quarantine' | 'timeout';
+            const action = workerTransition[2] as 'renew' | 'release' | 'sanitize' | 'quarantine' | 'timeout' | 'reap';
+            if (action === 'reap') {
+              if (!machine) throw new ResourceLedgerError(403, 'worker-reap-host-required');
+              const body = podWorkerBody(await req.json());
+              const podUid = body.podUid;
+              if (typeof podUid !== 'string' || !podUid.trim()) throw new ResourceLedgerError(400, 'invalid-pod-worker-reap');
+              const id = `pod-worker-lease:${workerId}`;
+              requireTarget(id);
+              const stale = await currentWorkerPrimary();
+              if (stale) return stale;
+              return json(await ledger.withGuardedWorkerMutation(async () => !(await currentWorkerPrimary()),
+                () => ledger.reservePodWorkerReap(id, { machine, podUid })));
+            }
             if (action === 'timeout') {
               if (scope !== 'member') throw new ResourceLedgerError(403, 'worker-timeout-scope');
               const body = podWorkerBody(await req.json());

package/src/core-turn/deep-turn-bloom.ts

@@ -0,0 +1,67 @@
+export type DeepBloomTrigger = 'research-intent' | 'deep-question' | 'high-reasoning-effort';
+
+export type DeepBloomDecision =
+  | { apply: true; reason: DeepBloomTrigger }
+  | { apply: false; reason: 'lightweight' | 'no-deep-signal' };
+
+export type DeepBloomInstruction = Extract<DeepBloomDecision, { apply: true }> & {
+  levels: readonly [4, 5];
+  questionCount: 3 | 4 | 5;
+  prompt?: string;
+  exemplarDomain?: string;
+  exemplarLevels?: number[];
+};
+
+const LIGHTWEIGHT_TEXT = /^(?:hi|hello|hey|thanks|thank you|good morning|good night|안녕(?:하세요)?|고마워(?:요)?|감사합니다|잘 자(?:요)?)[.!?\s]*$/iu;
+const LIGHTWEIGHT_FACT = /^(?:what(?:'s| is)\s+(?:the\s+)?(?:capital|time|date|meaning|definition)\b.*|who is\b.*|where is\b.*|몇 시(?:야|인가요)?|오늘 날짜(?:는|가)?|\S+의 뜻(?:은|이)?)[?？.!\s]*$/iu;
+const LIGHTWEIGHT_COMMAND = /^(?:please\s+)?(?:open|show|list|translate|convert|print|set|turn on|turn off)\b|^(?:열어(?:줘|주세요)|보여(?:줘|주세요)|나열해(?:줘|주세요)|번역해(?:줘|주세요)|계산해(?:줘|주세요)|켜(?:줘|주세요)|꺼(?:줘|주세요))\s*$/iu;
+const DEEP_QUESTION = /\b(?:analy[sz]e|analysis|evaluate|evaluation|compare|comparison|outlook|forecast|cause|causes|why|impact|trade-?offs?|pros and cons|design|strategy|scenario|counterargument|assess|judge)\b|분석|평가|비교|전망|예측|원인|영향|장단점|설계|전략|시나리오|반박|판단|어떻게 봐야|왜\b/iu;
+
+/** Lightweight turns have precedence so effort settings never inflate greetings, simple facts, or direct commands. */
+export function selectDeepBloom(
+  request: string | undefined,
+  options: { researchIntent?: boolean; reasoningEffort?: string } = {},
+): DeepBloomDecision {
+  const text = request?.trim() ?? '';
+  if (!text || LIGHTWEIGHT_TEXT.test(text) || LIGHTWEIGHT_FACT.test(text) || LIGHTWEIGHT_COMMAND.test(text))
+    return { apply: false, reason: 'lightweight' };
+  if (options.researchIntent) return { apply: true, reason: 'research-intent' };
+  if (options.reasoningEffort && ['high', 'xhigh', 'max'].includes(options.reasoningEffort))
+    return { apply: true, reason: 'high-reasoning-effort' };
+  if (DEEP_QUESTION.test(text)) return { apply: true, reason: 'deep-question' };
+  return { apply: false, reason: 'no-deep-signal' };
+}
+
+/** Build a hidden same-call analysis/evaluation instruction with the existing KGS Bloom cells and exemplar bank. */
+export async function buildDeepBloomInstruction(
+  request: string,
+  trigger: DeepBloomTrigger,
+): Promise<DeepBloomInstruction> {
+  const [{ BLOOM_2D_SCOPED }, { getBloomExemplarContext }] = await Promise.all([
+    import('../knowledge/kgs/types.js'), import('../research/bloom-exemplars.js'),
+  ]);
+  const analyze = BLOOM_2D_SCOPED.find((cell) => cell.cognitive === 'analyze')!;
+  const evaluate = BLOOM_2D_SCOPED.find((cell) => cell.cognitive === 'evaluate')!;
+  const exemplar = getBloomExemplarContext(request);
+  const prompt = [
+    'Before answering, silently ask yourself 3–5 short questions and answer them from the available context.',
+    `Analysis focus (${analyze.cognitive}/${analyze.knowledge}): break the subject into components, relationships, and causal mechanisms.`,
+    `Evaluation focus (${evaluate.cognitive}/${evaluate.knowledge}): set explicit criteria, compare alternatives or claims, and test at least one counterargument.`,
+    'Use those answers to produce a clear conclusion. Do not expose these internal labels or a checklist unless the user asks for the reasoning process.',
+    exemplar.context,
+  ].filter(Boolean).join('\n\n');
+  return { apply: true, reason: trigger, levels: [4, 5], questionCount: 4,
+    prompt, exemplarDomain: exemplar.domain, exemplarLevels: exemplar.levels };
+}
+
+/** Ensure the existing research ladder gives levels 4 and 5 distinct analysis/evaluation work. */
+export async function buildResearchBloom45Directive(): Promise<string> {
+  const { BLOOM_2D_SCOPED } = await import('../knowledge/kgs/types.js');
+  const analyze = BLOOM_2D_SCOPED.find((cell) => cell.cognitive === 'analyze')!;
+  const evaluate = BLOOM_2D_SCOPED.find((cell) => cell.cognitive === 'evaluate')!;
+  return [
+    `For Bloom level 4 (${analyze.cognitive}/${analyze.knowledge}), ask about components, relationships, and causal mechanisms.`,
+    `For Bloom level 5 (${evaluate.cognitive}/${evaluate.knowledge}), ask for criteria-based judgment across alternatives and a counterargument.`,
+    'Keep both questions request-specific and ensure each has search terms; do not duplicate level 3 or level 6 work.',
+  ].join('\n');
+}

package/src/core-turn/research-policy.ts

@@ -0,0 +1,43 @@
+/** Shared guardrails for every core-turn research surface. */
+export const RESEARCH_TURN_MAX_TOOL_TURNS = 20;
+export const RESEARCH_TURN_FIRST_REPLY_BUDGET_MS = 15_000;
+/** Research returns its best partial evidence before the parent has to abort the turn. */
+export const RESEARCH_TURN_FINAL_ANSWER_DEADLINE_MS = 8 * 60_000;
+export const RESEARCH_TURN_DEEP_BUDGET_MS = 9 * 60_000;
+export const RESEARCH_TURN_SHALLOW_BUDGET_MS = 3 * 60_000;
+/** Leave time for shallow partial-answer synthesis before the unchanged parent timeout. */
+export const RESEARCH_TURN_SHALLOW_FINAL_ANSWER_DEADLINE_MS = RESEARCH_TURN_SHALLOW_BUDGET_MS - 10_000;
+export const RESEARCH_TURN_DEADLINE_STOP_ERROR = 'research stopped by its deadline';
+
+/** Research turns only receive these tools; unrelated writers are never implicit. */
+export const RESEARCH_TOOL_ALLOWLIST = [
+  'OmniSearch',
+  'WebSearch',
+  'WebFetch',
+  'Agent',
+  'Read',
+  // TUI quick-route contracts: every quick turn can recall memory, and the
+  // investigation route may list (but never mutate) the seat mailbox.
+  'memory_recall',
+  'MsgList',
+] as const;
+
+const RESEARCH_TOOL_NAMES: ReadonlySet<string> = new Set(RESEARCH_TOOL_ALLOWLIST);
+export const RESEARCH_DOCUMENT_WRITE_TOOLS = ['Edit', 'Write'] as const;
+
+/** A research turn may write only when the user explicitly asks for a document at a concrete path. */
+const DOCUMENT_OUTPUT_PATH = /(?:^|[\s"'\x60])(?:\.{1,2}\/)?(?:[\w.-]+\/)*[\w.-]+\.(?:md|mdx|txt|rst|adoc|html|json|ya?ml|csv)\b/i;
+const DOCUMENT_OUTPUT_PATH_GLOBAL = /(?:^|[\s"'\x60])(?:\.{1,2}\/)?(?:[\w.-]+\/)*[\w.-]+\.(?:md|mdx|txt|rst|adoc|html|json|ya?ml|csv)\b/gi;
+const POSITIVE_DOCUMENT_WRITE_INTENT = /\b(?:write|writes|writing|written|draft|drafts|drafting|create|creates|creating|author|authors|authoring|produce|produces|producing|save|saves|saving)\b|작성|초안|생성|기록/i;
+const NEGATED_DOCUMENT_WRITE_INTENT = /\b(?:do\s+not|don['’]?t|never|must\s+not|should\s+not|avoid)\s+(?:(?:be|to)\s+)*(?:write|writes|writing|written|draft|drafts|drafting|create|creates|creating|author|authors|authoring|produce|produces|producing|save|saves|saving)\b|(?:작성|초안|생성|기록)(?:\s*(?:을|를))?\s*(?:하지\s*마|하지\s*말|하지\s*않|금지)/i;
+
+/** A research turn may write only when the user explicitly asks for a document at a concrete path. */
+export function requestsResearchDocumentWrite(text: string | undefined): boolean {
+  if (!text || !DOCUMENT_OUTPUT_PATH.test(text)) return false;
+  const intentText = text.replace(DOCUMENT_OUTPUT_PATH_GLOBAL, ' ');
+  return POSITIVE_DOCUMENT_WRITE_INTENT.test(intentText)
+    && !NEGATED_DOCUMENT_WRITE_INTENT.test(intentText);
+}
+export function isResearchToolAllowed(name: string): boolean {
+  return RESEARCH_TOOL_NAMES.has(name);
+}