elanous 0.2.0 → 0.2.5

package/src/steward/directive.ts

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { getUserConfig } from '../user-config.js';
+
+export type DirectiveSource = 'telegram' | 'pwa' | 'tui' | 'cli';
+export interface DirectiveIssue { id: string; identifier: string; title: string; description?: string | null }
+export interface DirectiveDeps {
+  fetch?: typeof fetch;
+  getSecret?: (id: string) => Promise<string | undefined>;
+  team?: string;
+  now?: () => Date;
+}
+
+export function directiveHash(text: string): string {
+  return createHash('sha256').update(text.normalize('NFKC').trim().replace(/\s+/g, ' ').toLocaleLowerCase()).digest('hex');
+}
+
+async function graphql<T>(key: string, query: string, variables: Record<string, unknown>, fetchFn: typeof fetch): Promise<T> {
+  let response: Response;
+  try {
+    response = await fetchFn('https://api.linear.app/graphql', {
+      method: 'POST', headers: { Authorization: key, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables }),
+    });
+  } catch { throw new Error('Linear GraphQL request failed'); }
+  if (!response.ok) throw new Error(`Linear GraphQL HTTP ${response.status}`);
+  let payload: { data?: T; errors?: unknown[] };
+  try { payload = await response.json() as typeof payload; }
+  catch { throw new Error('Linear GraphQL invalid JSON response'); }
+  if (payload.errors?.length || !payload.data) throw new Error('Linear GraphQL returned errors or missing data');
+  return payload.data;
+}
+
+/** The same entry point is used by the CLI and conversational surfaces. */
+export async function addDirective(text: string, options: { source?: DirectiveSource; dryRun?: boolean } = {}, deps: DirectiveDeps = {}): Promise<{ status: 'created' | 'repeated' | 'dry-run'; issue?: string; hash: string }> {
+  const original = text.trim();
+  if (!original) throw new Error('directive text is required');
+  const source = options.source ?? 'cli';
+  if (!['telegram', 'pwa', 'tui', 'cli'].includes(source)) throw new Error('invalid directive source');
+  const hash = directiveHash(original);
+  if (options.dryRun) return { status: 'dry-run', hash };
+  const key = await (deps.getSecret ?? getSecretAsync)('connector.linear.apiKey');
+  if (!key) throw new Error('connector.linear.apiKey missing; run elanous connector linear set-key');
+  const teamKey = deps.team ?? getUserConfig().loops?.steward?.linearTeam ?? 'ELA';
+  const request = <T>(query: string, variables: Record<string, unknown>) => graphql<T>(key, query, variables, deps.fetch ?? fetch);
+  const team = await request<{ teams: { nodes: Array<{ id: string }> } }>(
+    'query($key:String!){teams(filter:{key:{eq:$key}}){nodes{id}}}', { key: teamKey });
+  const teamId = team.teams?.nodes?.[0]?.id;
+  if (!teamId) throw new Error('Linear team not found');
+  let after: string | null = null;
+  const seen = new Set<string>();
+  let duplicate: DirectiveIssue | undefined;
+  do {
+    const data: { issues: { nodes: Array<DirectiveIssue & { state?: { type?: string } }>; pageInfo: { hasNextPage: boolean; endCursor: string | null } } } = await request<{ issues: { nodes: Array<DirectiveIssue & { state?: { type?: string } }>; pageInfo: { hasNextPage: boolean; endCursor: string | null } } }>(
+      'query($key:String!,$after:String){issues(filter:{team:{key:{eq:$key}}},first:100,after:$after){nodes{id identifier title description state{type}} pageInfo{hasNextPage endCursor}}}',
+      { key: teamKey, after });
+    if (!Array.isArray(data.issues?.nodes)) throw new Error('Linear issues missing');
+    duplicate = data.issues.nodes.find(issue => {
+      if (['completed', 'canceled', 'duplicate'].includes(issue.state?.type ?? '')) return false;
+      if (issue.description?.includes(`[directive-hash:${hash}]`)) return true;
+      const firstLine = issue.description?.split('\n')[0]?.trim();
+      const candidate = firstLine && firstLine.length > 0 ? firstLine : issue.title;
+      return directiveHash(candidate) === hash;
+    });
+    if (duplicate) break;
+    const page = data.issues.pageInfo;
+    if (page?.hasNextPage && (!page.endCursor || seen.has(page.endCursor))) throw new Error('Linear pagination cursor missing or repeated');
+    after = page?.hasNextPage ? page.endCursor : null;
+    if (after) seen.add(after);
+  } while (after);
+  const at = (deps.now ?? (() => new Date()))().toISOString();
+  if (duplicate) {
+    const result = await request<{ commentCreate: { success: boolean } }>(
+      'mutation($input:CommentCreateInput!){commentCreate(input:$input){success}}',
+      { input: { issueId: duplicate.id, body: `다시 말함 · ${source} · ${at}\n\n${original}` } });
+    if (!result.commentCreate?.success) throw new Error('Linear comment creation failed');
+    return { status: 'repeated', issue: duplicate.identifier, hash };
+  }
+  const labels = await request<{ issueLabels: { nodes: Array<{ id: string; name: string }> } }>(
+    'query($name:String!){issueLabels(filter:{name:{eq:$name}}){nodes{id name}}}', { name: 'from-directive' });
+  let labelId = labels.issueLabels?.nodes?.find(item => item.name === 'from-directive')?.id;
+  if (!labelId) {
+    const createdLabel = await request<{ issueLabelCreate: { success: boolean; issueLabel?: { id: string } } }>(
+      'mutation($input:IssueLabelCreateInput!){issueLabelCreate(input:$input){success issueLabel{id}}}',
+      { input: { teamId, name: 'from-directive' } });
+    labelId = createdLabel.issueLabelCreate?.success ? createdLabel.issueLabelCreate.issueLabel?.id : undefined;
+    if (!labelId) throw new Error('Linear label from-directive creation failed');
+  }
+  const created = await request<{ issueCreate: { success: boolean; issue?: DirectiveIssue } }>(
+    'mutation($input:IssueCreateInput!){issueCreate(input:$input){success issue{id identifier title}}}',
+    { input: { teamId, title: original.slice(0, 240), description: `${original}\n\n출처: ${source}\n시각: ${at}\n[directive-hash:${hash}]`, labelIds: [labelId], priority: 0 } });
+  if (!created.issueCreate?.success || !created.issueCreate.issue?.identifier) throw new Error('Linear issue creation failed');
+  return { status: 'created', issue: created.issueCreate.issue.identifier, hash };
+}
+
+export async function runDirectiveCli(text: string, options: { source?: DirectiveSource; dryRun?: boolean }): Promise<void> {
+  const result = await addDirective(text, options);
+  console.log(`${result.status}\t${result.issue ?? '-'}\t${result.hash}`);
+}

package/src/steward/steward-cards.ts

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { CardStore, redactSecrets, type AppendSectionInput, type CreateCardInput, type TaskCard } from '../task-cards/card-store.js';
+import type { ScheduledDecision, TriageIssue } from './triage.js';
+
+export interface StewardCardStore {
+  createCard(input: CreateCardInput): TaskCard;
+  appendSection(id: string, input: AppendSectionInput): TaskCard;
+  close(): void;
+}
+
+export interface StewardCardDeps {
+  store?: StewardCardStore;
+  root?: string;
+  now?: () => Date;
+}
+
+/** Record observe-only intake and the latest scheduled judgment without launching any work. */
+export function recordTriageOnCards(decisions: ScheduledDecision[], issues: TriageIssue[], deps: StewardCardDeps = {}): void {
+  const store = deps.store ?? new CardStore(deps.root);
+  const byIssue = new Map(issues.map(issue => [issue.identifier, issue]));
+  try {
+    for (const decision of decisions) {
+      const issue = byIssue.get(decision.issue);
+      if (!issue) throw new Error(`Missing issue ${decision.issue}`);
+      const card = store.createCard({ goalId: `linear:${issue.identifier}`, title: redactSecrets(issue.title) });
+      const intakeKey = `intake:${issue.identifier}`;
+      if (!card.sections.some(section => section.key === intakeKey)) {
+        const directiveSource = /^출처: (telegram|pwa|tui|cli)$/m.exec(issue.body)?.[1];
+        const directiveTime = /^시각: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)$/m.exec(issue.body)?.[1];
+        store.appendSection(card.id, {
+          key: intakeKey, owner: 'steward',
+          content: JSON.stringify({ summary: redactSecrets(issue.title), source: directiveSource ?? `linear:${issue.identifier}`, at: directiveTime ?? (deps.now ?? (() => new Date()))().toISOString() }),
+        });
+      }
+      const { rung, dependsOn, priority, disposition, hitlReason, why, owner } = decision;
+      const judgment = { rung, dependsOn, priority, disposition: rung === 'hitl' || hitlReason ? 'hitl' : disposition, hitlReason: hitlReason ?? null, why: redactSecrets(why), ...(owner ? { owner } : {}) };
+      const key = `triage:${createHash('sha256').update(JSON.stringify(judgment)).digest('hex')}`;
+      if (!card.sections.some(section => section.key === key)) {
+        store.appendSection(card.id, { key, owner: 'steward', content: JSON.stringify(judgment) });
+      }
+    }
+  } finally {
+    if (!deps.store) store.close();
+  }
+}

package/src/steward/triage.ts

@@ -0,0 +1,239 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fetchLinearIssues } from '../connectors/linear.js';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { getUserConfig } from '../user-config.js';
+import { emitDecision } from '../live/detail-switch.js';
+import { debug, redactSecretText } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { redactSecrets } from '../task-cards/card-store.js';
+import { directiveHash } from './directive.js';
+import { recordTriageOnCards, type StewardCardDeps } from './steward-cards.js';
+
+export type Rung = 0 | 1 | 2 | 3 | 4 | 5 | 'hitl';
+/** `other` = the judge chose human review for a reason outside the four named ones (kept as HITL, never downgraded). */
+export type HitlReason = 'money' | 'public' | 'security' | 'irreversible' | 'other';
+export interface TriageIssue { identifier: string; ref: string; title: string; body: string }
+export interface TriageDecision {
+  issue: string; rung: Rung; dependsOn: string[]; priority: number; duplicateOf?: string;
+  hitlReason?: HitlReason; why: string; role?: string; cost?: number;
+  /** Owner track from `loops.steward.tracks` (absent when no table is configured or the judge picked none of its keys). */
+  owner?: string;
+}
+export interface ScheduledDecision extends TriageDecision { disposition: 'now' | 'wait' | 'hitl' }
+export interface StewardSettings {
+  mode?: 'observe' | 'act'; linearTeam?: string;
+  roles?: Record<string, { maxConcurrent?: number }>;
+  budget?: number;
+  tracks?: Record<string, string>;
+}
+export interface StewardDeps {
+  fetch?: typeof fetch;
+  getSecret?: (id: string) => Promise<string | undefined>;
+  judge?: (issue: TriageIssue, issues: TriageIssue[], tracks?: Record<string, string>) => Promise<unknown>;
+  decide?: typeof emitDecision;
+  sendDigest?: (text: string) => Promise<void>;
+  now?: () => Date;
+  root?: string;
+  cardStore?: StewardCardDeps['store'];
+  warn?: (message: string) => void;
+}
+
+export function stewardSettings(): StewardSettings {
+  return getUserConfig().loops?.steward ?? {};
+}
+
+const unsafe: Array<[HitlReason, RegExp]> = [
+  ['money', /돈|유료|결제|구매|판매|송금|환불|크레딧\s*(?:추가|구매)|paid|payment|purchase/i],
+  ['public', /공개|발행|외부\s*게시|publish|public\s*release/i],
+  ['security', /보안|(?:키|자격|권한|secret|credential|permission)\s*(?:변경|교체|발급|삭제|공유|노출)|키체인/i],
+  ['irreversible', /비가역|강제\s*푸시|force.push|영구\s*삭제|리셋권\s*소비|drop\s*table|초기화/i],
+];
+
+function parseJudgment(issue: TriageIssue, raw: unknown, tracks?: Record<string, string>): TriageDecision {
+  const value = typeof raw === 'string' ? JSON.parse(raw) as unknown : raw;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid triage judgment: ${issue.identifier}`);
+  const d = value as Record<string, unknown>;
+  if (![0, 1, 2, 3, 4, 5, 'hitl'].includes(d.rung as Rung) ||
+      !Array.isArray(d.dependsOn) || !d.dependsOn.every(v => typeof v === 'string') ||
+      typeof d.priority !== 'number' || !Number.isFinite(d.priority) || typeof d.why !== 'string' || !d.why.trim()) {
+    throw new Error(`Invalid triage judgment: ${issue.identifier}`);
+  }
+  const forced = unsafe.find(([, pattern]) => pattern.test(`${issue.title}\n${issue.body}`))?.[0];
+  const named = forced ?? (unsafe.some(([reason]) => reason === d.hitlReason) ? d.hitlReason as HitlReason : undefined);
+  // A HITL judgment without one of the four named reasons stays HITL (`other`) — one issue must not stop the stage.
+  const hitlReason = named ?? (d.rung === 'hitl' ? 'other' as const : undefined);
+  return {
+    issue: issue.identifier, rung: hitlReason ? 'hitl' : d.rung as Rung,
+    dependsOn: d.dependsOn as string[], priority: d.priority as number,
+    ...(typeof d.duplicateOf === 'string' ? { duplicateOf: d.duplicateOf } : {}),
+    ...(hitlReason ? { hitlReason } : {}), why: (d.why as string).trim().replace(/\s+/g, ' '),
+    ...(typeof d.role === 'string' ? { role: d.role } : {}),
+    ...(typeof d.cost === 'number' && Number.isFinite(d.cost) && d.cost >= 0 ? { cost: d.cost } : {}),
+    ...(tracks && typeof d.owner === 'string' && Object.hasOwn(tracks, d.owner) ? { owner: d.owner } : {}),
+  };
+}
+
+/** The role table as prompt lines — read from config so a reorg edits one place. */
+export function trackTablePrompt(tracks?: Record<string, string>): string {
+  if (!tracks || !Object.keys(tracks).length) return '';
+  const keys = Object.keys(tracks);
+  return `\n담당 트랙(owner) — 아래 중 하나(${keys.map(k => JSON.stringify(k)).join('|')}) · 이슈가 어느 트랙 일인지:\n${keys.map(k => `- ${k}: ${tracks[k]}`).join('\n')}`;
+}
+
+async function judgeStewardIssue(issue: TriageIssue, issues: TriageIssue[], tracks?: Record<string, string>): Promise<unknown> {
+  const ownerField = tracks && Object.keys(tracks).length ? `,"owner":${JSON.stringify(Object.keys(tracks)[0])}` : '';
+  const prompt = `스튜어드 트리아지. JSON 객체만 출력: {"rung":0|1|2|3|4|5|"hitl","dependsOn":[],"priority":1,"duplicateOf":null,"hitlReason":null,"why":"한 문장","role":"builder","cost":0${ownerField}}.\n0=이미됨/중복, 1=셸, 2=CLI, 3=조사, 4=하니스 골, 5=외부 에이전트. 돈·공개·보안·비가역은 hitl(hitlReason = "money"|"public"|"security"|"irreversible" · 그 밖의 이유로 사람 확인이 필요하면 "other"). 확인되지 않은 완료/중복은 추측하지 마라. 의존은 제공된 이슈 키만 써라.${trackTablePrompt(tracks)}\n이슈 목록: ${JSON.stringify(issues.map(i => ({ key: i.identifier, title: i.title })))}\n판정 대상: ${JSON.stringify(issue)}`;
+  const { streamLLM } = await import('../llm.js');
+  const { tierModel } = await import('../llm/model-defaults.js');
+  const result = await streamLLM([{ role: 'user', content: prompt }], () => {}, { model: tierModel('best') });
+  return JSON.parse(result.replace(/^```(?:json)?\s*|\s*```$/g, '').trim()) as unknown;
+}
+
+export async function triageIssues(issues: TriageIssue[], judge: NonNullable<StewardDeps['judge']> = judgeStewardIssue, decide: typeof emitDecision = emitDecision, tracks?: Record<string, string>): Promise<TriageDecision[]> {
+  const decisions: TriageDecision[] = [];
+  for (const issue of issues) {
+    let result: TriageDecision;
+    try {
+      result = parseJudgment(issue, await judge(issue, issues, tracks), tracks);
+    } catch (error) {
+      // A malformed or failed judgment for one issue goes to a human; the other issues are still triaged.
+      try { debug.log('steward.stage', 'judgment-invalid', { issue: issue.identifier, reason: redactSecrets(String(error)) }); } catch { /* fail-soft */ }
+      result = { issue: issue.identifier, rung: 'hitl', hitlReason: 'other', dependsOn: [], priority: 0, why: 'triage judgment unavailable — human review' };
+    }
+    decisions.push(result);
+    decide({ kind: result.rung === 'hitl' ? 'ESCALATE' : 'ROUTE', what: issue.identifier, reason: result.why,
+      purpose: 'steward triage', target: result.owner ? `${result.rung} · ${result.owner}` : String(result.rung), refs: { issue: issue.identifier } });
+  }
+  return decisions;
+}
+
+/** Stable priority-ordered topological schedule; missing/cyclic dependencies wait, never auto-approve. */
+export function scheduleTriage(decisions: TriageDecision[], settings: StewardSettings = {}, running: Record<string, number> = {}, completed: ReadonlySet<string> = new Set()): ScheduledDecision[] {
+  const byId = new Map(decisions.map(d => [d.issue, d]));
+  if (byId.size !== decisions.length) throw new Error('Duplicate issue identifier');
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const sorted: TriageDecision[] = [];
+  const visit = (item: TriageDecision): void => {
+    if (visited.has(item.issue) || visiting.has(item.issue)) return;
+    visiting.add(item.issue);
+    for (const dep of item.dependsOn) { const upstream = byId.get(dep); if (upstream) visit(upstream); }
+    visiting.delete(item.issue); visited.add(item.issue); sorted.push(item);
+  };
+  for (const item of [...decisions].sort((a, b) => a.priority - b.priority || a.issue.localeCompare(b.issue))) visit(item);
+  const slots = { ...running };
+  let remaining = settings.budget ?? Infinity;
+  return sorted.map(item => {
+    const role = item.owner ?? item.role ?? String(item.rung);
+    const max = settings.roles?.[role]?.maxConcurrent ?? Infinity;
+    const blocked = item.dependsOn.some(dep => !completed.has(dep));
+    const status: ScheduledDecision['disposition'] = item.rung === 'hitl' || item.hitlReason ? 'hitl' :
+      item.rung === 0 || item.duplicateOf || blocked || (slots[role] ?? 0) >= max || (item.cost ?? 0) > remaining ? 'wait' : 'now';
+    if (status === 'now') { slots[role] = (slots[role] ?? 0) + 1; remaining -= item.cost ?? 0; }
+    return { ...item, disposition: status };
+  });
+}
+
+async function linear<T>(key: string, query: string, variables: Record<string, unknown>, fetchFn: typeof fetch): Promise<T> {
+  let response: Response;
+  try { response = await fetchFn('https://api.linear.app/graphql', { method: 'POST', headers: { Authorization: key, 'Content-Type': 'application/json' }, body: JSON.stringify({ query, variables }) }); }
+  catch { throw new Error('Linear GraphQL request failed'); }
+  if (!response.ok) throw new Error(`Linear GraphQL HTTP ${response.status}`);
+  let body: { data?: T; errors?: unknown[] };
+  try { body = await response.json() as typeof body; }
+  catch { throw new Error('Linear GraphQL invalid JSON response'); }
+  if (body.errors?.length || !body.data) throw new Error('Linear GraphQL returned errors or missing data');
+  return body.data;
+}
+
+function reportPath(root: string): string { return join(root, 'steward', 'observe.json'); }
+function readState(path: string): { issues: Record<string, string>; digestDay?: string } {
+  try { return JSON.parse(readFileSync(path, 'utf8')) as ReturnType<typeof readState>; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { issues: {} }; throw error; }
+}
+
+/** Each command node invokes one stage. No stage can spawn, launch, merge or approve. */
+export async function runStewardStage(stage: 'sync' | 'triage' | 'schedule' | 'report', deps: StewardDeps = {}): Promise<void> {
+  const settings = stewardSettings();
+  if ((settings.mode ?? 'observe') !== 'observe') throw new Error('steward act mode is out of scope');
+  const key = await (deps.getSecret ?? getSecretAsync)('connector.linear.apiKey');
+  if (!key) throw new Error('connector.linear.apiKey missing');
+  const root = deps.root ?? effectiveInstanceRoot();
+  const dir = join(root, 'steward');
+  mkdirSync(dir, { recursive: true });
+  const snapshot = join(dir, 'issues.json');
+  const judgments = join(dir, 'triage.json');
+  const schedule = join(dir, 'schedule.json');
+  const fetchFn = deps.fetch ?? fetch;
+  if (stage === 'sync') {
+    const events = await fetchLinearIssues({ apiKey: key, teamKey: settings.linearTeam ?? 'ELA', fetch: fetchFn });
+    writeFileSync(snapshot, JSON.stringify(events.map(e => ({ identifier: e.identifier, ref: e.ref, title: e.title, body: e.body }))));
+  } else if (stage === 'triage') {
+    const issues = JSON.parse(readFileSync(snapshot, 'utf8')) as TriageIssue[];
+    const judge = deps.judge ?? judgeStewardIssue;
+    writeFileSync(judgments, JSON.stringify(await triageIssues(issues, judge, deps.decide, settings.tracks)));
+  } else if (stage === 'schedule') {
+    const decisions = JSON.parse(readFileSync(judgments, 'utf8')) as TriageDecision[];
+    const pending = new Set(decisions.flatMap(decision => decision.dependsOn));
+    const completed = new Set<string>();
+    for (const identifier of pending) {
+      const data = await linear<{ issue: { identifier: string; state?: { type: string } } | null }>(key,
+        'query($id:String!){issue(id:$id){identifier state{type}}}', { id: identifier }, fetchFn);
+      if (data.issue?.identifier === identifier && data.issue.state?.type === 'completed') completed.add(identifier);
+    }
+    writeFileSync(schedule, JSON.stringify(scheduleTriage(decisions, settings, {}, completed)));
+  } else {
+    const rows = JSON.parse(readFileSync(schedule, 'utf8')) as ScheduledDecision[];
+    const path = reportPath(root);
+    const state = readState(path);
+    const at = (deps.now ?? (() => new Date()))().toISOString();
+    const issues = JSON.parse(readFileSync(snapshot, 'utf8')) as TriageIssue[];
+    try {
+      recordTriageOnCards(rows, issues, { root, store: deps.cardStore, now: deps.now });
+    } catch (error) {
+      const message = `steward report: card write failed: ${redactSecrets(error instanceof Error ? error.message : String(error))}`;
+      debug.log('steward.cards', 'write-failed', { error: message });
+      (deps.warn ?? console.warn)(message);
+    }
+    for (const row of rows) {
+      const issue = issues.find(item => item.identifier === row.issue);
+      if (!issue) throw new Error(`Missing issue ${row.issue}`);
+      const body = `스튜어드 observe · ${row.disposition} · rung ${row.rung} · 우선순위 ${row.priority} · 의존 ${row.dependsOn.join(', ') || '없음'}${row.duplicateOf ? ` · 중복 ${row.duplicateOf}` : ''} · ${row.why}${row.hitlReason ? ` · HITL ${row.hitlReason}` : ''}`;
+      const hash = directiveHash(body);
+      if (state.issues[row.issue] === hash) continue;
+      const result = await linear<{ commentCreate: { success: boolean } }>(key, 'mutation($input:CommentCreateInput!){commentCreate(input:$input){success}}', { input: { issueId: issue.ref, body } }, fetchFn);
+      if (!result.commentCreate?.success) throw new Error(`Linear comment failed: ${row.issue}`);
+      state.issues[row.issue] = hash;
+      writeFileSync(path, JSON.stringify(state));
+    }
+    const day = at.slice(0, 10);
+    if (state.digestDay !== day) {
+      const send = deps.sendDigest ?? sendStewardDigest;
+      await send(`스튜어드 ${day}: ${rows.map(row => `${row.issue} ${row.disposition}`).join(' · ')}`);
+      state.digestDay = day;
+      writeFileSync(path, JSON.stringify(state));
+    }
+  }
+}
+
+async function sendStewardDigest(text: string): Promise<void> {
+  const { deliver } = await import('../domains/outbound-alert.js');
+  if (!deliver(text, 'digest')) throw new Error('steward digest delivery failed');
+}
+
+if (import.meta.main) {
+  const stage = process.argv[2];
+  if (!['sync', 'triage', 'schedule', 'report'].includes(stage ?? '')) {
+    console.error('steward: expected sync|triage|schedule|report');
+    process.exitCode = 2;
+  } else {
+    runStewardStage(stage as 'sync' | 'triage' | 'schedule' | 'report').catch((error: unknown) => {
+      // Say why (secrets masked) — 09-29 the first resident run failed as a bare «stage failed» on a missing Linear key.
+      const reason = redactSecretText(error instanceof Error ? error.message : String(error)).slice(0, 300);
+      console.error(`steward ${stage}: stage failed — ${reason}`);
+      debug.log('steward.stage', 'failed', { stage, reason });
+      process.exitCode = 1;
+    });
+  }
+}

package/src/storage/cli-bin.ts

@@ -0,0 +1,67 @@
+// 클라우드 CLI 경로 한 곳.
+// gcloud 순서는 role-cli 의 gcloudSearchPaths() 를 그대로 따른다(복제 금지).
+// 나머지(aws·az·wrangler)는 알려진 설치 경로 → PATH.
+
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { gcloudSearchPaths } from '../cli/role-cli.js';
+
+export type CliBinName = 'gcloud' | 'aws' | 'az' | 'wrangler';
+
+export interface CliBinDeps {
+  /** 후보 경로가 실행 파일로 있나. 없으면 existsSync. */
+  exists?: (path: string) => boolean;
+  /** PATH. 없으면 process.env.PATH. gcloud 는 gcloudSearchPaths() 가 이미 PATH 를 담는다. */
+  pathEnv?: string;
+  home?: string;
+  /** 시험이 후보 나열을 바꾼다. 없으면 모듈 훅 → 기본 표. */
+  candidates?: (name: CliBinName) => readonly string[];
+}
+
+const KNOWN_BIN_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '~/.local/bin'] as const;
+
+type SearchFn = (name: CliBinName, deps: CliBinDeps) => readonly string[];
+let searchOverride: SearchFn | null = null;
+
+/** 시험 전용 — 후보 나열을 바꾼다(`null` = 되돌림). 진짜 CLI 가 깔린 기계에서 가짜 경로만 보게. */
+export function _setCliBinSearchForTesting(fn: SearchFn | null): void {
+  searchOverride = fn;
+}
+
+function expandHome(dir: string, home: string): string {
+  if (dir === '~') return home;
+  if (dir.startsWith('~/')) return join(home, dir.slice(2));
+  return dir;
+}
+
+function fileExists(path: string, exists: (path: string) => boolean): boolean {
+  try { return exists(path); } catch { return false; }
+}
+
+/** 이름별 후보. gcloud 는 gcloudSearchPaths() 순서 그대로. */
+export function cliBinCandidates(name: CliBinName, deps: CliBinDeps = {}): readonly string[] {
+  if (deps.candidates) return deps.candidates(name);
+  if (searchOverride) return searchOverride(name, deps);
+  if (name === 'gcloud') return gcloudSearchPaths();
+  const home = deps.home ?? process.env.HOME ?? '';
+  const dirs = KNOWN_BIN_DIRS.map((dir) => expandHome(dir, home));
+  const pathEnv = deps.pathEnv ?? process.env.PATH ?? '';
+  const fromPath = pathEnv.split(delimiter).filter(Boolean);
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const dir of [...dirs, ...fromPath]) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    out.push(join(dir, name));
+  }
+  return out;
+}
+
+/** 첫 실행 파일. 없으면 null. */
+export function resolveCliBin(name: CliBinName, deps: CliBinDeps = {}): string | null {
+  const exists = deps.exists ?? existsSync;
+  for (const path of cliBinCandidates(name, deps)) {
+    if (fileExists(path, exists)) return path;
+  }
+  return null;
+}

package/src/storage/object-store-visibility.ts

@@ -0,0 +1,169 @@
+// 공급자별 공개/비공개 판정. 명령 실패·모르는 문면은 unreadable — private 으로 통과시키지 않는다.
+
+import { judgeArchiveBucket, type BucketState } from '../webclone/archive-bucket-verdict.js';
+import { isFullyBlockedFromPublic, isPublicReadPolicy } from '../webclone/webclone-store.js';
+import type { RunFn, StorageProvider } from './object-store.js';
+
+export type Visibility = 'private' | 'public' | 'partially-public' | 'missing' | 'unreadable';
+
+export interface VisibilityVerdict {
+  visibility: Visibility;
+  reason: string;
+}
+
+export interface VisibilityDeps {
+  run: RunFn;
+  which?: (name: string) => string;
+}
+
+function whichOf(deps: VisibilityDeps, name: string): string {
+  return deps.which?.(name) ?? name;
+}
+
+function mapS3State(state: BucketState): Visibility {
+  if (state === 'blocked') return 'private';
+  if (state === 'public-policy') return 'public';
+  if (state === 'partially-blocked' || state === 'no-block-config') return 'partially-public';
+  if (state === 'missing') return 'missing';
+  return 'unreadable';
+}
+
+function probeS3Family(provider: 's3' | 'r2', bucket: string, deps: VisibilityDeps, endpoint?: string[]): VisibilityVerdict {
+  const bin = whichOf(deps, 'aws');
+  const extra = endpoint ?? [];
+  let policy: { ok: boolean; text: string };
+  let block: { ok: boolean; text: string };
+  try {
+    const out = deps.run(bin, ['s3api', 'get-bucket-policy', '--bucket', bucket, '--output', 'text', ...extra], { timeoutMs: 30_000 });
+    policy = { ok: true, text: out.stdout };
+  } catch (e) {
+    policy = { ok: false, text: (e as Error).message ?? '' };
+  }
+  try {
+    const out = deps.run(bin, ['s3api', 'get-public-access-block', '--bucket', bucket, ...extra], { timeoutMs: 30_000 });
+    block = { ok: true, text: out.stdout };
+  } catch (e) {
+    block = { ok: false, text: (e as Error).message ?? '' };
+  }
+  if (!policy.ok && !block.ok && !/NoSuch|PublicAccess|policy/i.test(`${policy.text}\n${block.text}`)) {
+    return { visibility: 'unreadable', reason: `${provider} 명령을 읽지 못했다` };
+  }
+  const judged = judgeArchiveBucket(bucket, { policy, block }, isPublicReadPolicy, isFullyBlockedFromPublic);
+  return { visibility: mapS3State(judged.state), reason: judged.why };
+}
+
+function probeGcs(bucket: string, deps: VisibilityDeps): VisibilityVerdict {
+  const bin = whichOf(deps, 'gcloud');
+  let described: string;
+  try {
+    described = deps.run(bin, ['storage', 'buckets', 'describe', `gs://${bucket}`, '--format=json'], { timeoutMs: 30_000 }).stdout;
+  } catch (e) {
+    const msg = (e as Error).message ?? '';
+    if (/not found|404/i.test(msg)) return { visibility: 'missing', reason: `버킷 «${bucket}» 이 없다` };
+    return { visibility: 'unreadable', reason: 'gcs 버킷 설명을 읽지 못했다' };
+  }
+  let pap: unknown;
+  try {
+    const j = JSON.parse(described) as { public_access_prevention?: unknown; iamConfiguration?: { publicAccessPrevention?: unknown } };
+    pap = j.public_access_prevention ?? j.iamConfiguration?.publicAccessPrevention;
+  } catch {
+    return { visibility: 'unreadable', reason: 'gcs 버킷 설명을 해석하지 못했다' };
+  }
+  let policyText: string;
+  try {
+    policyText = deps.run(bin, ['storage', 'buckets', 'get-iam-policy', `gs://${bucket}`, '--format=json'], { timeoutMs: 30_000 }).stdout;
+  } catch {
+    return { visibility: 'unreadable', reason: 'gcs IAM 정책을 읽지 못했다' };
+  }
+  let world = false;
+  try {
+    const policy = JSON.parse(policyText) as { bindings?: Array<{ members?: string[] }> };
+    const members = (policy.bindings ?? []).flatMap((b) => b.members ?? []);
+    world = members.some((m) => m === 'allUsers' || m === 'allAuthenticatedUsers');
+  } catch {
+    return { visibility: 'unreadable', reason: 'gcs IAM 정책을 해석하지 못했다' };
+  }
+  if (world) return { visibility: 'public', reason: 'allUsers 또는 allAuthenticatedUsers 가 IAM 에 있다' };
+  if (pap === 'enforced') return { visibility: 'private', reason: 'public_access_prevention=enforced' };
+  if (pap === 'inherited') return { visibility: 'partially-public', reason: 'public_access_prevention=inherited — 비공개로 단정하지 않는다' };
+  return { visibility: 'unreadable', reason: 'public_access_prevention 문면을 모른다' };
+}
+
+function probeAzure(bucket: string, deps: VisibilityDeps, account: string): VisibilityVerdict {
+  if (!account) return { visibility: 'unreadable', reason: 'azure.account 가 없다' };
+  const bin = whichOf(deps, 'az');
+  let accountJson: string;
+  try {
+    accountJson = deps.run(bin, ['storage', 'account', 'show', '--name', account], { timeoutMs: 30_000 }).stdout;
+  } catch {
+    return { visibility: 'unreadable', reason: 'azure 계정 설명을 읽지 못했다' };
+  }
+  let allow: unknown;
+  try {
+    const j = JSON.parse(accountJson) as { allowBlobPublicAccess?: unknown };
+    allow = j.allowBlobPublicAccess;
+  } catch {
+    return { visibility: 'unreadable', reason: 'azure 계정 설명을 해석하지 못했다' };
+  }
+  if (allow === false) return { visibility: 'private', reason: 'allowBlobPublicAccess=false' };
+  let perm: string;
+  try {
+    perm = deps.run(bin, [
+      'storage', 'container', 'show-permission',
+      '--account-name', account,
+      '--name', bucket,
+      '--auth-mode', 'login',
+    ], { timeoutMs: 30_000 }).stdout;
+  } catch (e) {
+    const msg = (e as Error).message ?? '';
+    if (/ContainerNotFound|not found|404/i.test(msg)) return { visibility: 'missing', reason: `컨테이너 «${bucket}» 이 없다` };
+    return { visibility: 'unreadable', reason: 'azure 컨테이너 권한을 읽지 못했다' };
+  }
+  let publicAccess: unknown;
+  try {
+    const j = JSON.parse(perm) as { publicAccess?: unknown };
+    publicAccess = j.publicAccess;
+  } catch {
+    return { visibility: 'unreadable', reason: 'azure 컨테이너 권한을 해석하지 못했다' };
+  }
+  if (publicAccess === 'off' || publicAccess === 'none' || publicAccess === null || publicAccess === undefined || publicAccess === '') {
+    return { visibility: 'private', reason: 'publicAccess 가 꺼져 있다' };
+  }
+  if (publicAccess === 'blob' || publicAccess === 'container') {
+    return { visibility: 'public', reason: `publicAccess=${String(publicAccess)}` };
+  }
+  return { visibility: 'unreadable', reason: 'azure publicAccess 문면을 모른다' };
+}
+
+export interface ProbeVisibilityOpts {
+  /** r2 엔드포인트에 필요한 계정. s3 에는 쓰지 않는다. */
+  accountId?: string;
+  /** azure --account-name. */
+  account?: string;
+  /** r2/s3 --profile. */
+  profile?: string;
+}
+
+/** 공급자별 가시성. local 은 항상 private. 실패·모르는 문면은 unreadable. */
+export function probeVisibility(
+  provider: StorageProvider,
+  bucket: string,
+  deps: VisibilityDeps,
+  opts: ProbeVisibilityOpts = {},
+): VisibilityVerdict {
+  if (provider === 'local') return { visibility: 'private', reason: '로컬 파일은 공개 URL 이 없다' };
+  if (!bucket) return { visibility: 'missing', reason: '버킷 이름이 없다' };
+  if (provider === 's3') {
+    const extra = opts.profile ? ['--profile', opts.profile] : [];
+    return probeS3Family('s3', bucket, deps, extra);
+  }
+  if (provider === 'r2') {
+    if (!opts.accountId) return { visibility: 'unreadable', reason: 'r2.accountId 가 없다' };
+    const extra = ['--endpoint-url', `https://${opts.accountId}.r2.cloudflarestorage.com`];
+    if (opts.profile) extra.push('--profile', opts.profile);
+    return probeS3Family('r2', bucket, deps, extra);
+  }
+  if (provider === 'gcs') return probeGcs(bucket, deps);
+  if (provider === 'azure') return probeAzure(bucket, deps, opts.account ?? '');
+  return { visibility: 'unreadable', reason: '모르는 공급자다' };
+}