elanous 0.2.21 → 0.2.22

package/src/nexus/api/graphs-api.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { debug } from '../../debug/log.js';
@@ -10,6 +11,7 @@ import { validateGraphYaml } from './graph-kinds.js';
 import { parseWizardSteps, readWizardSteps, withWizardSteps } from '../../graph-wizard/saved-steps.js';
 import type { WizardNodeStep } from '../../graph-wizard/steps.js';
 import { jsonResponse } from './json-response.js';
+import { clearPeerEdit, peerEditRefusalBody, peerEditRunGate, readPeerEdit, writePeerEdit } from './graph-peer-edit.js';
 
 /** Declared graph ids only. A user string is never joined onto a filesystem path. */
 const GRAPH_ID = /^[a-z0-9-]+$/;
@@ -44,6 +46,93 @@ function mineGraphsDir(): string {
   return join(elanousStateRoot(), 'graphs');
 }
 
+export type GraphPermission = 'view' | 'edit';
+type GraphGrant = { recipient: string; permission: GraphPermission };
+const TOKEN_PATTERN = /^eg_[A-Za-z0-9_-]{32,}$/;
+
+function accessFile(dir: string, id: string): string {
+  return join(dir, '.access', `${id}.json`);
+}
+function tokenHash(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+function accessGrants(dir: string, id: string): GraphGrant[] {
+  let text: string;
+  try { text = readFileSync(accessFile(dir, id), 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const parsed: unknown = JSON.parse(text);
+  if (!Array.isArray(parsed) || !parsed.every((entry): entry is GraphGrant => entry !== null && typeof entry === 'object'
+    && typeof entry.recipient === 'string' && /^[a-f0-9]{64}$/.test(entry.recipient)
+    && (entry.permission === 'view' || entry.permission === 'edit'))) throw new Error('invalid graph access store');
+  return parsed;
+}
+
+/** Only a hash is persisted; no owner bearer or raw recipient credential goes into a graph/YAML. */
+export function handleGraphAccess(pathname: string, req: Request, deps: GraphsApiDeps = {}): Response {
+  const match = /^\/v1\/graphs\/([^/]+)\/access$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id) return jsonResponse({ error: 'bad_request' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  try { return jsonResponse({ grants: accessGrants(owned.mineDir, id) }); }
+  catch (error) { return saveFailed(id, error); }
+}
+
+export async function handleGraphAccessPut(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/access$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id) return jsonResponse({ error: 'bad_request' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  // Detail GET resolves a core id first; do not grant a token for a shadowed mine id.
+  if (indexByDeclaredId(deps.coreDir ?? defaultGraphsDir()).has(id)) return jsonResponse({ error: 'core-id-conflict', id }, 409);
+  let body: { recipient?: unknown; permission?: unknown };
+  try { body = await req.json() as typeof body; }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body.recipient !== 'string' || !TOKEN_PATTERN.test(body.recipient)
+    || (body.permission !== 'view' && body.permission !== 'edit')) {
+    return jsonResponse({ error: 'bad_request', reason: 'recipient access token and view/edit permission required' }, 400);
+  }
+  const recipient = tokenHash(body.recipient);
+  const dir = join(owned.mineDir, '.access');
+  try {
+    const grants = accessGrants(owned.mineDir, id).filter((grant) => grant.recipient !== recipient);
+    grants.push({ recipient, permission: body.permission });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = accessFile(owned.mineDir, id);
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify(grants), { mode: 0o600 });
+      renameSync(temp, target);
+    } finally { rmSync(temp, { force: true }); }
+  } catch (error) { return saveFailed(id, error); }
+  return jsonResponse({ recipient, permission: body.permission });
+}
+
+/** The peer token works only on this graph and the requested read/edit operation. */
+export function graphAccessForRequest(pathname: string, method: string, token: string | null, deps: GraphsApiDeps = {}): boolean {
+  const match = /^\/v1\/graphs\/([^/]+)(?:\/(yaml))?$/.exec(pathname);
+  const id = match ? resolveId(match[1]!) : null;
+  if (!id || !token || !TOKEN_PATTERN.test(token)) return false;
+  if (method !== 'GET' && !(method === 'PUT' && match?.[2] === 'yaml')) return false;
+  try {
+    if (!indexByDeclaredId(deps.mineDir ?? mineGraphsDir()).has(id)) return false;
+    if (indexByDeclaredId(deps.coreDir ?? defaultGraphsDir()).has(id)) return false;
+    const wanted = tokenHash(token);
+    return accessGrants(deps.mineDir ?? mineGraphsDir(), id).some((grant) => {
+      const stored = Buffer.from(grant.recipient, 'hex');
+      return timingSafeEqual(stored, Buffer.from(wanted, 'hex')) && (method === 'GET' || grant.permission === 'edit');
+    });
+  } catch (error) {
+    debug.log('nexus.graphs', 'access-read-failed', { id, reason: String(error) }, { level: 'warn' });
+    return false;
+  }
+}
+
 function resolveId(raw: string): string | null {
   let id: string;
   try { id = decodeURIComponent(raw); }
@@ -203,7 +292,10 @@ export function handleGraphsGet(pathname: string, dir = defaultGraphsDir(), deps
 }
 
 /** PUT writes only under the state-root graphs directory. Core YAML is never opened for write. */
-export async function handleGraphsPut(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+/** Who authorized a save: the owner, or a peer token holding an «edit» grant (raw token; only a hash prefix is kept). */
+export type GraphSaveActor = { peerToken: string } | null;
+
+export async function handleGraphsPut(pathname: string, req: Request, deps: GraphsApiDeps = {}, actor: GraphSaveActor = null): Promise<Response> {
   const match = /^\/v1\/graphs\/([^/]+)\/yaml$/.exec(pathname);
   if (!match) return jsonResponse({ error: 'not-found' }, 404);
   const id = resolveId(match[1]!);
@@ -229,11 +321,21 @@ export async function handleGraphsPut(pathname: string, req: Request, deps: Grap
   // Writes go only to <mine>/<id>.yaml; a hand-placed file under another name is not edited over HTTP.
   if (existing.file !== `${id}.yaml`) return jsonResponse({ error: 'file-name-mismatch', id, file: existing.file }, 409);
   let written: { version: string; previous: string };
-  try { written = withWizardSteps(mineDir, id, steps, () => writeWithVersion(mineDir, id, existing, body.yaml as string)); }
+  const editedBy = actor ? `peer:${tokenHash(actor.peerToken).slice(0, 8)}` : null;
+  try {
+    written = withWizardSteps(mineDir, id, steps, () => {
+      // Peer save: the marker goes down «before» the bytes, so a crash in between still refuses the run.
+      if (editedBy) writePeerEdit(mineDir, id, { editedBy, version: 'pending', at: new Date().toISOString() });
+      const result = writeWithVersion(mineDir, id, existing, body.yaml as string);
+      if (editedBy) writePeerEdit(mineDir, id, { editedBy, version: result.version, at: new Date().toISOString() });
+      else clearPeerEdit(mineDir, id);
+      return result;
+    });
+  }
   catch (error) { return saveFailed(id, error); }
   const { version, previous } = written;
-  debug.log('nexus.graphs', 'saved', { id, version, previous, steps: steps ? Object.keys(steps).length : 0 });
-  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous });
+  debug.log('nexus.graphs', 'saved', { id, version, previous, steps: steps ? Object.keys(steps).length : 0, ...(editedBy ? { editedBy } : {}) });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous, ...(editedBy ? { editedBy } : {}) });
 }
 
 const VERSION_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z(?:-\d{4})?$/;
@@ -408,8 +510,14 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
-  const source = indexByDeclaredId(coreDir).get(id) ?? indexByDeclaredId(mineDir).get(id);
+  const fromCore = indexByDeclaredId(coreDir).get(id);
+  const source = fromCore ?? indexByDeclaredId(mineDir).get(id);
   if (!source) return jsonResponse({ error: 'not-found', id }, 404);
+  // A clone would carry a peer's unapproved change into a graph with no marker — approve first.
+  if (!fromCore) {
+    const gate = peerEditRunGate(mineDir, id);
+    if (!gate.ok) return jsonResponse(peerEditRefusalBody(id, gate), 409);
+  }
   if (indexByDeclaredId(mineDir).has(body.newId) || indexByDeclaredId(coreDir).has(body.newId)) {
     return jsonResponse({ error: 'conflict', id: body.newId }, 409);
   }
@@ -422,9 +530,39 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   return jsonResponse({ id: body.newId, source: 'mine', editable: true, clonedFrom: id }, 201);
 }
 
-export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response | null> {
+/** POST /v1/graphs/<id>/approve {version} — owner only (the route never accepts a peer token). Approves the
+ *  exact peer version the run refusal named; a newer peer save is a new version and needs a new approval. */
+export async function handleGraphsApprove(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/approve$/.exec(pathname);
+  if (!match) return jsonResponse({ error: 'not-found' }, 404);
+  const id = resolveId(match[1]!);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  let body: { version?: unknown };
+  try { body = await req.json() as { version?: unknown }; }
+  catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  if (typeof body?.version !== 'string' || !body.version) return jsonResponse({ error: 'bad_request', reason: 'version string required' }, 400);
+  let record;
+  try { record = readPeerEdit(owned.mineDir, id); }
+  catch (error) { return saveFailed(id, error); }
+  if (!record) return jsonResponse({ id, approved: true, version: body.version, pending: false });
+  if (record.version !== body.version) {
+    return jsonResponse({ error: 'version-mismatch', id, version: record.version, reason: '승인하려는 판이 최신 상대 변경과 다르다 — 다시 확인하라' }, 409);
+  }
+  const approved = { version: record.version, at: new Date().toISOString() };
+  try { writePeerEdit(owned.mineDir, id, { ...record, approved }); }
+  catch (error) { return saveFailed(id, error); }
+  debug.log('nexus.graphs', 'peer-edit-approved', { id, version: record.version, editedBy: record.editedBy });
+  return jsonResponse({ id, approved: true, version: record.version, editedBy: record.editedBy });
+}
+
+export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}, actor: GraphSaveActor = null): Promise<Response | null> {
+  // Only PUT …/yaml is open to a peer token; every other mutation is the owner's alone.
+  if (actor && !(req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname))) return jsonResponse({ error: 'unauthorized' }, 401);
   if (req.method === 'POST' && pathname === '/v1/graphs') return handleGraphsCreate(req, deps);
-  if (req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname)) return handleGraphsPut(pathname, req, deps);
+  if (req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname)) return handleGraphsPut(pathname, req, deps, actor);
+  if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/approve$/.test(pathname)) return handleGraphsApprove(pathname, req, deps);
   if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/clone$/.test(pathname)) return handleGraphsClone(pathname, req, deps);
   if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/revert$/.test(pathname)) return handleGraphsRevert(pathname, req, deps);
   return null;

package/src/nexus/api/http-server.ts

@@ -19,7 +19,9 @@ import { setInProcessOutbound } from '../../domains/outbound-alert.js';
 import { getUserConfig } from '../../user-config.js';
 import type { TelegramEvent } from '../../workflow-runtime/triggers/telegram-source.js';
 import { spawnSync } from 'node:child_process';
-import { isAbsolute } from 'node:path';
+import { isAbsolute, join, dirname, relative } from 'node:path';
+import { homedir } from 'node:os';
+import { readdirSync, realpathSync, statSync } from 'node:fs';
 import { createProject, listProjects } from '../../project/project-store.js';
 import { handleOutputsGet, type OutputsDeps } from './outputs-route.js';
 import { buildGridData, type GridDeps } from './grid.js';
@@ -368,12 +370,12 @@ import {
 } from './workflows.js';
 import { handleTriggersSnapshot } from './triggers.js';
 import { handleWorkflowTemplatesList } from './workflow-templates.js';
-import { handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
+import { graphAccessForRequest, handleGraphAccess, handleGraphAccessPut, handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
 import { handleGraphKindsGet, handleGraphsValidatePost } from './graph-kinds.js';
-import { handleGraphWizardPost } from './graph-wizard-api.js';
+import { handleGraphWizardPost, handleGraphWizardPacksGet } from './graph-wizard-api.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
-import { handlePluginsIndexGet, handlePluginsGet, handlePluginsMarketRefresh, handlePluginsInstall, handlePluginsRemove } from './plugins-market.js';
+import { handlePluginsIndexGet, handlePluginsGet, handlePluginsMarketRefresh, handlePluginsInstall, handlePluginsRemove, handlePluginWizardList, handlePluginWizardSave } from './plugins-market.js';
 import { handlePluginsCredentialsGet, handlePluginsCredentialsPut } from './plugins-credentials-api.js';
 import {
   handleWorkflowsList,
@@ -489,6 +491,8 @@ export interface NexusHttpServerOpts {
   fabricPlans?: FabricPlansRouteOpts;
   /** GRAPH-WIZARD 시험 주입(LLM·템플릿 뿌리). 운영은 비워 둔다. */
   graphWizard?: import('../../graph-wizard/generate.js').GraphWizardDeps;
+  /** Roots the remote folder picker may browse (default: the daemon user's home). Tests inject a temp root. */
+  projectFolderRoots?: string[];
   /** Optional installer state root for isolated API consumers and tests. */
   pluginStateRoot?: string;
   outputs?: OutputsDeps;
@@ -846,6 +850,55 @@ export function handleProjectsGet(): Response {
   return jsonResponse({ projects: listProjects() });
 }
 
+function isWithinRoot(path: string, root: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * Remote folder picker: lists sub-folders under an allow-listed root only.
+ * Every path is resolved with realpath first, so `..` segments and symlinks cannot escape the roots;
+ * dot-folders are hidden and symlinked entries that point outside the roots are not listed.
+ */
+export function handleProjectFoldersGet(req: Request, roots: string[] = [homedir()]): Response {
+  const allowed: string[] = [];
+  for (const root of roots) {
+    try { allowed.push(realpathSync(root)); } catch { /* a missing root grants nothing */ }
+  }
+  if (allowed.length === 0) return jsonResponse({ error: 'folder_unavailable' }, 404);
+  const requested = new URL(req.url).searchParams.get('path') ?? allowed[0]!;
+  if (!isAbsolute(requested) || requested.includes('\0')) return jsonResponse({ error: 'invalid_folder' }, 400);
+  let path: string;
+  try { path = realpathSync(requested); }
+  catch {
+    debug.log('nexus.projects', 'folders-unavailable', { reason: 'missing' });
+    return jsonResponse({ error: 'folder_unavailable' }, 404);
+  }
+  if (!allowed.some(root => isWithinRoot(path, root))) {
+    debug.log('nexus.projects', 'folders-refused', { reason: 'outside-roots' });
+    return jsonResponse({ error: 'outside_allowed_roots' }, 403);
+  }
+  try {
+    if (!statSync(path).isDirectory()) return jsonResponse({ error: 'not_directory' }, 400);
+    const folders = readdirSync(path, { withFileTypes: true })
+      .filter(entry => {
+        if (entry.name.startsWith('.')) return false;
+        if (entry.isDirectory()) return true;
+        if (!entry.isSymbolicLink()) return false;
+        try {
+          const target = realpathSync(join(path, entry.name));
+          return statSync(target).isDirectory() && allowed.some(root => isWithinRoot(target, root));
+        } catch { return false; }
+      })
+      .map(entry => ({ name: entry.name, path: join(path, entry.name) }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const atRoot = allowed.includes(path);
+    return jsonResponse({ path, parent: atRoot ? null : dirname(path), folders });
+  } catch {
+    return jsonResponse({ error: 'folder_unavailable' }, 404);
+  }
+}
+
 export async function handleProjectsPost(req: Request): Promise<Response> {
   let body: unknown;
   try { body = await req.json(); }
@@ -996,7 +1049,9 @@ export async function routeRequest(
     const offered = req.headers.get('authorization');
     const fallbackAuthorized = fallbackToken !== undefined && offered?.startsWith('Bearer ') === true
       && compareTokenConstTime(offered.slice('Bearer '.length).trim(), fallbackToken);
-    if (!(opts.metaApi ? checkAuth(req, opts.metaApi) : fallbackAuthorized)) {
+    const graphPeerAuthorized = (method === 'GET' || method === 'PUT')
+      && graphAccessForRequest(pathname, method, offered?.startsWith('Bearer ') ? offered.slice(7).trim() : null);
+    if (!(opts.metaApi ? checkAuth(req, opts.metaApi) : fallbackAuthorized) && !graphPeerAuthorized) {
       const name = method === 'POST' && (pathname === '/v1/tasks' || pathname === '/v1/reports/ingest') && opts.metaApi
         ? matchIngestAuthorization(req)?.name
         : undefined;
@@ -1407,7 +1462,12 @@ export async function routeRequest(
     return handleGraphsValidatePost(req, opts.metaApi);
   }
 
-  // GRAPH-WIZARD — 말 → 그래프 YAML(저장 안 함). 다른 /v1/graphs 쓰기와 같은 인증.
+  // GRAPH-WIZARD — 설치된 팩 목록과 말 → 그래프 YAML(저장 안 함). 같은 소유자 인증.
+  if (method === 'GET' && pathname === '/v1/graphs/wizard/packs') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphWizardPacksGet(opts.graphWizard);
+  }
   if (method === 'POST' && pathname === '/v1/graphs/wizard') {
     if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
     if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
@@ -1419,6 +1479,10 @@ export async function routeRequest(
     return handleFabricPlans(req, opts.fabricPlans);
   }
 
+  if (pathname === '/v1/projects/folders' && method === 'GET') {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleProjectFoldersGet(req, opts.projectFolderRoots);
+  }
   if (pathname === '/v1/projects' && (method === 'GET' || method === 'POST')) {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return method === 'GET' ? handleProjectsGet() : handleProjectsPost(req);
@@ -1515,6 +1579,10 @@ export async function routeRequest(
         ...opts.decisions,
       });
     }
+    if (method === 'POST' && pathname === '/v1/plugins/wizard') {
+      if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
+      return handlePluginWizardSave(req, opts.metaApi, opts.pluginStateRoot);
+    }
     if (method === 'POST' && pathname === '/v1/plugins/install') {
       if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
       return handlePluginsInstall(req, opts.metaApi, opts.pluginStateRoot);
@@ -1534,10 +1602,19 @@ export async function routeRequest(
       if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
       return handlePluginsRemove(req, pluginRemove[1]!, opts.metaApi, opts.pluginStateRoot);
     }
+    if (method === 'PUT' && /^\/v1\/graphs\/[^/]+\/access$/.test(pathname)) {
+      if (!opts.metaApi || bearerCredential(req, opts.metaApi) === undefined) return jsonResponse({ error: 'unauthorized' }, 401);
+      return handleGraphAccessPut(pathname, req);
+    }
     if ((method === 'PUT' || method === 'POST') && (pathname.startsWith('/v1/graphs/') || pathname === '/v1/graphs')) {
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
-      if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
-      const mutated = await handleGraphsMutation(pathname, req);
+      const peerMayEdit = method === 'PUT' && graphAccessForRequest(pathname, method,
+        req.headers.get('authorization')?.startsWith('Bearer ') ? req.headers.get('authorization')!.slice(7).trim() : null);
+      const ownerAuthorized = checkAuth(req, opts.metaApi);
+      if (!ownerAuthorized && !peerMayEdit) return jsonResponse({ error: 'unauthorized' }, 401);
+      // A peer save is recorded on the graph so every run path refuses it until the owner approves (W9c run guard).
+      const mutated = await handleGraphsMutation(pathname, req, {}, ownerAuthorized ? null
+        : { peerToken: req.headers.get('authorization')!.slice(7).trim() });
       if (mutated) return mutated;
     }
     const cardClose = /^\/v1\/task-cards\/([^/]+)\/close$/.exec(pathname);
@@ -2829,6 +2906,10 @@ export async function routeRequest(
   // surface (`/v1/workflows` · `~/.elanous/workflows-runs/`) covers the same
   // user need.
 
+  if (method === 'GET' && pathname === '/v1/plugins/wizard') {
+    if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handlePluginWizardList(req, opts.metaApi, opts.pluginStateRoot);
+  }
   const pluginCredentialsGet = /^\/v1\/plugins\/([^/]+)\/credentials$/.exec(pathname);
   if (method === 'GET' && pluginCredentialsGet) {
     if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
@@ -2844,6 +2925,10 @@ export async function routeRequest(
     catch (error) { debug.log('graph.kinds', 'installed-sync-failed', { reason: String(error) }); }
     return handleGraphKindsGet(req, opts.metaApi);
   }
+  if (method === 'GET' && /^\/v1\/graphs\/[^/]+\/access$/.test(pathname)) {
+    if (!opts.metaApi || bearerCredential(req, opts.metaApi) === undefined) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphAccess(pathname, req);
+  }
   // F-M1 read + P-F1 raw YAML. Writes live in the mutation block and never touch core graphs/.
   if (method === 'GET' && (pathname === '/v1/graphs' || /^\/v1\/graphs\/[^/]+$/.test(pathname) || /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname))) {
     return handleGraphsGet(pathname);

package/src/nexus/api/plugins-market.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { listWizardDrafts, saveWizardDraft, type WizardResearchDraft } from '../../plugins/maker/wizard-generate.js';
 import { dirname, join } from 'node:path';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { debug } from '../../debug/log.js';
@@ -120,6 +121,29 @@ export function handlePluginsIndexGet(req: Request, opts: MetaApiOpts, root?: st
   return jsonResponse(readMarketIndex(root, configuredTrustedKeys(configPath)));
 }
 
+export function handlePluginWizardList(req: Request, opts: MetaApiOpts, root = elanousStateRoot()): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  return jsonResponse({ plugins: listWizardDrafts(join(root, 'plugins-local')) });
+}
+
+export async function handlePluginWizardSave(req: Request, opts: MetaApiOpts, root = elanousStateRoot()): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  let body: unknown;
+  try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'bad_request' }, 400);
+  const input = body as { name?: unknown; draft?: unknown; regenerate?: unknown };
+  if (typeof input.name !== 'string' || !/^[a-z0-9][a-z0-9-]{1,31}$/.test(input.name) ||
+    !input.draft || typeof input.draft !== 'object' || Array.isArray(input.draft) ||
+    (input.regenerate !== undefined && typeof input.regenerate !== 'boolean')) return jsonResponse({ error: 'bad_request' }, 400);
+  try {
+    saveWizardDraft(join(root, 'plugins-local'), input.name, input.draft as WizardResearchDraft, input.regenerate === true);
+    return jsonResponse({ name: input.name, saved: true });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'invalid draft';
+    return jsonResponse({ error: 'invalid_wizard_draft', reason: /already exists|research draft/.test(reason) ? reason : 'invalid draft' }, 422);
+  }
+}
+
 export function handlePluginsGet(req: Request, opts: MetaApiOpts, root?: string): Response {
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   return jsonResponse(listInstalledPlugins(root));

package/src/nexus/index.ts

@@ -2743,11 +2743,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     if ((getUserConfig().raw?.decisions as { cards?: unknown } | undefined)?.cards !== false && !isAutonomousRunContext()) {
       try {
         const { DecisionCardService } = await import('../decisions/decision-cards.js');
-        const { webPushDecisionTransport } = await import('../decisions/web-push-decision-cards.js');
+        const { webPushDecisionTransport, webPushUrgency } = await import('../decisions/web-push-decision-cards.js');
         const { listSubscriptions } = await import('../web-push/subscriptions.js');
         const { DecisionLedger } = await import('../decisions/decision-ledger.js');
         const ledger = new DecisionLedger();
-        const service = new DecisionCardService({ transport: webPushDecisionTransport(ledger), ownerIds: [], ledger });
+        const service = new DecisionCardService({ transport: webPushDecisionTransport(ledger), ownerIds: [], ledger,
+          sendFilter: (entry, now) => webPushUrgency(entry, now) !== 'not-urgent', deferredReason: webPushUrgency });
         await service.tick();
         webPushDecisionTimer = setInterval(() => {
           void service.tick().catch((error: unknown) => {

package/src/oauth/claude-pty-maturity.ts

@@ -0,0 +1,24 @@
+export type ClaudePtyMaturity =
+  | { readonly mature: true }
+  | { readonly mature: false; readonly why: 'too-few-samples' | 'completion-below-70' | 'unknown-screen-above-10' | 'intervention-above-0.2' | 'sample-unreadable' };
+
+export type ClaudePtyMaturitySample = {
+  readonly runCount: number;
+  readonly completedCount: number;
+  readonly unknownScreenCount: number;
+  readonly interventionCount: number;
+};
+
+/** 최근 런의 계수만 판정한다. 표본을 못 읽거나 계수가 불가능하면 성숙으로 추정하지 않는다. */
+export function judgeClaudePtyMaturity(sample: ClaudePtyMaturitySample | null | undefined): ClaudePtyMaturity {
+  if (!sample || ![sample.runCount, sample.completedCount, sample.unknownScreenCount, sample.interventionCount]
+    .every((count) => Number.isSafeInteger(count) && count >= 0)
+    || sample.completedCount > sample.runCount || sample.unknownScreenCount > sample.runCount) {
+    return { mature: false, why: 'sample-unreadable' };
+  }
+  if (sample.runCount < 10) return { mature: false, why: 'too-few-samples' };
+  if (sample.completedCount / sample.runCount < 0.7) return { mature: false, why: 'completion-below-70' };
+  if (sample.unknownScreenCount / sample.runCount > 0.1) return { mature: false, why: 'unknown-screen-above-10' };
+  if (sample.interventionCount / sample.runCount > 0.2) return { mature: false, why: 'intervention-above-0.2' };
+  return { mature: true };
+}

package/src/oauth/fallback-chain.ts

@@ -19,9 +19,10 @@
 //   지갑을 여는» 일이 없다. (2026-08-13 실측 · RESEARCH-grok-oauth-… §7b)
 
 import type { RotationCandidate } from './codex-account-rotation.js';
+import type { ClaudePtyMaturity } from './claude-pty-maturity.js';
 
 /** 체인에 놓을 수 있는 칸. ⛔ 모르는 이름은 «조용히 건너뛰지 않고» 거부한다(오타 방어). */
-export const FALLBACK_STEPS = ['codex-rotate', 'grok'] as const;
+export const FALLBACK_STEPS = ['codex-rotate', 'grok', 'claude-pty'] as const;
 export type FallbackStep = (typeof FALLBACK_STEPS)[number];
 
 /** 기본 체인 — ⛔⭐ **2026-08-20 에 `grok` 이 «기본»으로 들어왔다**(대표 지시).
@@ -75,8 +76,8 @@ export type RotationOutcome =
 export type FallbackDecision =
   /** codex 계정을 갈아탄다(종전 동작). */
   | { readonly action: 'codex-rotate'; readonly to: RotationCandidate }
-  /** 백엔드를 통째로 바꾼다. 지금은 grok 뿐. */
-  | { readonly action: 'switch-backend'; readonly backend: 'grok' }
+  /** 백엔드를 통째로 바꾼다. */
+  | { readonly action: 'switch-backend'; readonly backend: 'grok' | 'claude' }
   /** 아무것도 안 한다 — 이유를 «값으로» 남긴다. */
   | { readonly action: 'stay'; readonly why: StayReason };
 
@@ -96,7 +97,9 @@ export type StayReason =
   /** 다음 칸이 grok 인데 grok 자격이 «없다». */
   | 'grok-unavailable'
   /** grok 자격은 있는데 «잔량이 소진»됐다 — 자격 부재와 «다른 값»이다. */
-  | 'grok-exhausted';
+  | 'grok-exhausted'
+  /** claude PTY 의 최근 표본이 성숙 관문을 통과하지 못했거나 읽히지 않는다. */
+  | 'claude-pty-immature';
 
 type FallbackRunPosition =
   | { readonly currentCredentialRateLimited?: false; readonly currentStep?: FallbackStep }
@@ -120,6 +123,8 @@ export type FallbackInput = {
    *   (⇒ 그리고 그 사실은 관측에 값으로 남는다 — 「모르고 갔다」를 셀 수 있다.)
    */
   readonly grokQuota?: 'usable' | 'exhausted' | 'unknown';
+  /** 최근 claude PTY 표본의 순수 성숙 판정. 생략·못 읽음은 전환 불가. */
+  readonly claudePtyMaturity?: ClaudePtyMaturity;
   /**
    * `reset-credit-available` 에서 체인을 타지 않고 머문다.
    * 기본(생략·false)은 `no-candidate` 와 같이 `codex-rotate` 다음 칸을 찾는다.
@@ -148,12 +153,12 @@ export type FallbackInput = {
 export function decideFallback(input: FallbackInput): FallbackDecision {
   const {
     rotation, chain, currentStep, currentCredentialRateLimited = false,
-    grokAvailable, grokQuota = 'unknown', stayOnResetCreditAvailable = false,
+    grokAvailable, grokQuota = 'unknown', claudePtyMaturity, stayOnResetCreditAvailable = false,
   } = input;
 
   if (currentCredentialRateLimited) {
     if (currentStep === undefined) return { action: 'stay', why: 'chain-exhausted' };
-    return stepAfter(chain, currentStep, grokAvailable, grokQuota, 'chain-exhausted');
+    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
   }
   if (rotation.reason === 'explicit') return { action: 'stay', why: 'explicit' };
   if (rotation.reason === 'not-reached' || (rotation.reason === 'credit-pace' && !('to' in rotation))) {
@@ -167,13 +172,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
     // 회전이 답을 냈는데 체인이 codex-rotate 를 «빼» 놨다면 그 뜻을 존중하고
     // 다음 칸으로 간다(회전을 원치 않는 구성).
     if (chain.includes('codex-rotate')) return { action: 'codex-rotate', to: rotation.to };
-    return stepAfterCodex(chain, grokAvailable, grokQuota, 'chain-exhausted');
+    return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
   }
 
   // no-candidate | disabled | reset-credit-available(기본) — codex 축이 끝났다. 다음 칸을 본다.
   // ⛔ 다음 칸이 «없을 때»의 이름만 고른다. 진행(stepAfterCodex)은 그대로다.
   const fallbackWhy = stayReasonWhenCodexAxisEnds(rotation.reason === 'credit-pace' ? 'no-candidate' : rotation.reason);
-  return stepAfterCodex(chain, grokAvailable, grokQuota, fallbackWhy);
+  return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, fallbackWhy);
 }
 
 /** codex 축이 끝났는데 체인 다음 칸도 없을 때 머무는 이유.
@@ -191,9 +196,10 @@ function stepAfterCodex(
   chain: readonly FallbackStep[],
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
+  claudePtyMaturity: ClaudePtyMaturity | undefined,
   whyIfNone: StayReason,
 ): FallbackDecision {
-  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, whyIfNone);
+  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, whyIfNone);
 }
 
 function stepAfter(
@@ -201,20 +207,27 @@ function stepAfter(
   currentStep: FallbackStep | undefined,
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
+  claudePtyMaturity: ClaudePtyMaturity | undefined,
   whyIfNone: StayReason,
 ): FallbackDecision {
   const idx = currentStep === undefined ? -1 : chain.indexOf(currentStep);
   const rest = idx === -1 ? chain : chain.slice(idx + 1);
+  let unavailableWhy: StayReason | undefined;
   for (const step of rest) {
     if (step === 'grok') {
-      // ⛔ 자격 «먼저» — 자격이 없으면 잔량을 물을 것도 없다(그리고 두 사유는 다른 값이다).
-      if (!grokAvailable) return { action: 'stay', why: 'grok-unavailable' };
-      // ⛔ 「모른다」는 통과시킨다 — 못 읽었다고 갈 곳을 없애지 않는다(위 계약 주석).
-      if (grokQuota === 'exhausted') return { action: 'stay', why: 'grok-exhausted' };
+      // 자격 부재와 소진은 다른 값이다. 다음 칸이 있으면 그 칸을 살핀다.
+      if (!grokAvailable) { unavailableWhy = 'grok-unavailable'; continue; }
+      // 「모른다」는 통과시킨다 — 못 읽었다고 갈 곳을 없애지 않는다.
+      if (grokQuota === 'exhausted') { unavailableWhy = 'grok-exhausted'; continue; }
       return { action: 'switch-backend', backend: 'grok' };
     }
+    if (step === 'claude-pty') {
+      // 미성숙·못 읽음은 «건너뛴다» — 뒤에 다른 칸이 있으면 그 칸을 본다(없으면 이 사유로 머문다).
+      if (claudePtyMaturity?.mature !== true) { unavailableWhy = 'claude-pty-immature'; continue; }
+      return { action: 'switch-backend', backend: 'claude' };
+    }
   }
-  return { action: 'stay', why: whyIfNone };
+  return { action: 'stay', why: unavailableWhy ?? whyIfNone };
 }
 
 /** 사람이 읽는 한 줄 — 관측·CLI 표면용. ⛔ 토큰·계정 홈은 넣지 않는다. */

package/src/plugins/maker/market-bundle.ts

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { userConfigPath } from '../../user-config.js';
+import { scanKnowledgePackDlp } from '../../mss/logging/redaction.js';
 import { loadPluginManifestFromDir } from '../core/manifest.js';
 import { LEAK_MARKERS, loadPrivateRedactions, privateIdentifierMarkers, scanLeaks } from '../../../scripts/public-export.js';
 
@@ -56,6 +57,14 @@ export function bundleInstalledWizardPlugin(installedPath: string, outputDir: st
   if (!redactions) throw new Error('private export redaction list unavailable; market bundle refused');
   const hits = scanLeaks(source, files, [...LEAK_MARKERS, ...privateIdentifierMarkers(redactions)]);
   if (hits.length) throw new Error(`market bundle leak: ${hits.map(hit => `${hit.file}:${hit.line} ${hit.marker}`).join(', ')}`);
+  const dlpHits: string[] = [];
+  for (const file of files) {
+    const text = readFileSync(join(source, file), 'utf8');
+    const reasons = scanKnowledgePackDlp(text);
+    if (text.includes('\u0000')) reasons.push('unscannable-content');
+    if (reasons.length) dlpHits.push(`${file}: ${reasons.join(', ')}`);
+  }
+  if (dlpHits.length) throw new Error(`market bundle DLP: ${dlpHits.join('; ')}`);
   const config: unknown = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf8')) : {};
   if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('invalid market signing config');
   const signing = (config as { market?: { signing?: { keyId?: unknown; privateKey?: unknown } } }).market?.signing;

package/src/plugins/maker/plugin-maker.ts

@@ -146,7 +146,10 @@ export async function validatePluginDir(dir: string): Promise<string[]> {
   catch (error) { errors.push(`recipes.yaml 파싱 실패: ${String(error)}`); }
   if (!isRecord(recipes)) errors.push('recipes.yaml 은 맵이어야 한다');
   else for (const [id, recipe] of Object.entries(recipes)) {
-    if (!isRecord(recipe) || typeof recipe.command !== 'string' || !recipe.command.trim() ||
+    if (!isRecord(recipe) ||
+      (!(typeof recipe.command === 'string' && recipe.command.trim()) && !(typeof recipe.approval === 'string' && recipe.approval.trim())) ||
+      (recipe.command !== undefined && (typeof recipe.command !== 'string' || !recipe.command.trim())) ||
+      (recipe.approval !== undefined && (typeof recipe.approval !== 'string' || !recipe.approval.trim())) ||
       (recipe.timeout_ms !== undefined && (!Number.isSafeInteger(recipe.timeout_ms) || Number(recipe.timeout_ms) <= 0))) errors.push(`잘못된 recipe: ${id}`);
   }
   for (const graph of Array.isArray(graphs) ? graphs : []) {
@@ -162,11 +165,14 @@ export async function validatePluginDir(dir: string): Promise<string[]> {
       if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(template.graphId)) errors.push(`잘못된 graph_id: ${template.graphId}`);
       if (template.terminalNodes.length !== 2 || !template.terminalNodes.includes('done') || !template.terminalNodes.includes('failed')) errors.push('terminal_nodes 는 done, failed 이어야 한다');
       const executionNodes = template.nodes.filter(node => !template.terminalNodes.includes(node.nodeId));
-      if (executionNodes.length < 2 || executionNodes.length > 6) errors.push(`실행 노드는 2~6개여야 한다: ${executionNodes.length}개`);
+      if (executionNodes.length < 2) errors.push(`실행 노드는 2개 이상이어야 한다: ${executionNodes.length}개`);
       for (const node of template.nodes) {
         if (node.recipe.startsWith('cmd:')) {
           const id = node.recipe.slice(4);
-          if (!isRecord(recipes) || !isRecord(recipes[id]) || typeof recipes[id].command !== 'string' || !recipes[id].command) errors.push(`recipe ${id} 없음`);
+          if (!isRecord(recipes) || !isRecord(recipes[id]) || recipes[id].approval !== undefined || typeof recipes[id].command !== 'string' || !recipes[id].command.trim()) errors.push(`recipe ${id} 없음`);
+        } else if (node.recipe.startsWith('approval:')) {
+          const id = node.recipe.slice(9);
+          if (!isRecord(recipes) || !isRecord(recipes[id]) || typeof recipes[id].approval !== 'string' || !recipes[id].approval.trim()) errors.push(`approval recipe ${id} 없음`);
         } else if (node.recipe !== 'none') errors.push(`지원하지 않는 recipe: ${node.recipe}`);
       }
     } catch (error) { errors.push(`${graph} 파싱 실패: ${String(error)}`); }