graphlin 0.1.0

package/runtime/core/privacy.mjs

@@ -0,0 +1,206 @@
+import { CATEGORIES, KINDS, LIMITS, OUTCOMES, freeze, hash, integer, isId, opaque, plain } from './common.mjs';
+import { toolResultPaths } from './tool-discovery.mjs';
+
+const DEFAULT_EXCLUDES = Object.freeze([
+  '**/.git/**', '**/node_modules/**', '**/.env*', '**/.ssh/**', '**/.aws/**',
+  '**/.npmrc*', '**/.pypirc*', '**/.netrc*', '**/_netrc*', '**/.yarnrc*',
+  '**/.gitconfig', '**/.dockercfg', '**/.docker/config.json', '**/.kube/config',
+  '**/.config/gcloud/**', '**/.config/gh/hosts.yml', '**/.boto', '**/.s3cfg',
+  '**/.pgpass', '**/.my.cnf', '**/pip.conf', '**/pip.ini', '**/nuget.config', '**/auth.json',
+  '**/*credential*', '**/*secret*', '**/*.pem', '**/*.key', '**/*.p12', '**/*.pfx',
+  '**/id_rsa*', '**/id_ed25519*',
+]);
+export function createPolicy(options = {}) {
+  options = plain(options) ? options : {};
+  const excludePaths = [...new Set([...DEFAULT_EXCLUDES, ...(
+    Array.isArray(options.excludePaths) ? options.excludePaths.slice(0, 128)
+      .filter(p => typeof p === 'string' && p.length > 0 && p.length <= 256 && !/[\0\r\n]/.test(p))
+      .map(p => p.replaceAll('\\', '/').replace(/^\.\//, ''))
+      .filter(p => !DEFAULT_EXCLUDES.includes(p)).slice(0, 64) : []
+  )])].sort();
+  const fields = {
+    transmitSource: options.transmitSource === true,
+    displayEvidence: options.displayEvidence !== false,
+    persistEvidence: options.persistEvidence === true,
+    excludePaths,
+  };
+  return freeze({ ...fields, version: `policy-${hash(fields).slice(0, 32)}` });
+}
+
+function globRegex(pattern) {
+  let result = '';
+  for (let i = 0; i < pattern.length; i++) {
+    if (pattern[i] === '*' && pattern[i + 1] === '*') {
+      i++;
+      if (pattern[i + 1] === '/') { result += '(?:.*/)?'; i++; }
+      else result += '.*';
+    } else if (pattern[i] === '*') result += '[^/]*';
+    else if (pattern[i] === '?') result += '[^/]';
+    else result += pattern[i].replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+  }
+  return new RegExp(`^(?:${result})(?:/.*)?$`, 'i');
+}
+
+export function excluded(relativePath, policy) {
+  if (typeof relativePath !== 'string' || relativePath.length > 4096 || /[\0\r\n\\]/.test(relativePath)) return true;
+  const normalized = relativePath.replace(/^\.\//, '');
+  return createPolicy(policy).excludePaths.some(pattern => globRegex(pattern).test(normalized));
+}
+
+const SECRET_NAME = /(?:password|passwd|passphrase|pwd|apikey|accesskeyid|(?:access|secret|private|signing|encryption)key|token|secret|auth|credentials?)(?:value)?$/i;
+const ENV_NAME = String.raw`[A-Za-z_][A-Za-z0-9_]*`;
+const ENV_LOOKUP = '(?:' + [
+  String.raw`(?:process\.env|import\.meta\.env|Bun\.env)(?:\.${ENV_NAME}|\[\s*["']${ENV_NAME}["']\s*\])`,
+  String.raw`os\.environ\[\s*["']${ENV_NAME}["']\s*\]`,
+  String.raw`(?:os\.getenv|os\.environ\.get|Deno\.env\.get)\(\s*["']${ENV_NAME}["']\s*\)`,
+].join('|') + ')';
+const REFERENCE_VALUE = new RegExp(String.raw`^(?:${ENV_LOOKUP}|\$(?:${ENV_NAME}|\{${ENV_NAME}\})|(["'\x60])\$(?:${ENV_NAME}|\{(?:${ENV_NAME}|${ENV_LOOKUP})\})\1|""|''|\x60\x60|null\b|undefined\b)`);
+
+function referenceOnly(value) {
+  const reference = REFERENCE_VALUE.exec(value);
+  if (!reference) return false;
+  const tail = value.slice(reference[0].length);
+  const trivia = /^(?:\s|\/\*[\s\S]*?\*\/|\/\/[^\r\n]*)*/.exec(tail)[0];
+  const next = tail.slice(trivia.length);
+  if (!next || /^[;,})\]]/.test(next)) return true;
+  // A newline may terminate an assignment without a semicolon, but a continued
+  // expression (including a literal fallback) must never inherit the exemption.
+  return /[\r\n]/.test(trivia) &&
+    !/^(?:[.?'"\x60+*/%|&^<>=!:([\\-]|(?:in|instanceof|or|and|if|else)\b)/.test(next);
+}
+
+function privateBinding(text) {
+  // Match the entire binding/property name before normalizing separators.
+  // A word boundary immediately before "API_KEY" misses TYPESAFE_API_KEY and
+  // camelCase names. The value check deliberately withholds unknown expressions.
+  for (const match of text.matchAll(/\b([A-Za-z_$][\w$-]*)['"]?\s*(?:\]\s*)?([:=])\s*/g)) {
+    if (!SECRET_NAME.test(match[1].replace(/[_$-]/g, ''))) continue;
+    let value = text.slice(match.index + match[0].length);
+    // A common TypeScript scalar annotation is not the assigned value.
+    if (match[2] === ':') value = value.replace(/^(?:string|String)(?:\s*\|\s*(?:null|undefined))*\s*=\s*/, '');
+    if (!referenceOnly(value)) return true;
+  }
+  return false;
+}
+
+export function privateText(text) {
+  if (typeof text !== 'string') return true;
+  return /-----BEGIN (?:[A-Z ]*PRIVATE KEY|OPENSSH PRIVATE KEY)-----/i.test(text) ||
+    /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/.test(text) ||
+    /\b(?:gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,}|sk-(?:proj-)?[A-Za-z0-9_-]{16,})\b/.test(text) ||
+    /\b(?:authorization|proxy-authorization)\s*[:=]\s*['"]?(?:bearer|basic)\s+[^\s'"]+/i.test(text) ||
+    privateBinding(text) ||
+    /[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i.test(text) ||
+    /(?:^|[\s"'`(=])(?:\/(?:Users|home|private|etc|root)\/|[A-Za-z]:[\\/])/.test(text);
+}
+export function safeText(text, max = LIMITS.snippetChars) {
+  return typeof text === 'string' && text.length > 0 && text.length <= max &&
+    !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(text) &&
+    !privateText(text);
+}
+export function safeLabel(label) {
+  return safeText(label, LIMITS.labelChars) && !/[\r\n<>]/.test(label) && !/^(?:\/|https?:|file:|javascript:)/i.test(label);
+}
+
+const EVENTS = Object.freeze({
+  SessionStart: 'session.started', UserPromptSubmit: 'turn.prompted',
+  PreToolUse: 'tool.requested', PostToolUse: 'tool.succeeded',
+  PostToolUseFailure: 'tool.failed', PermissionDenied: 'tool.denied',
+  Interrupt: 'tool.interrupted', Stop: 'turn.stopped', SessionEnd: 'session.ended',
+  SubagentStart: 'agent.started', SubagentStop: 'agent.stopped',
+  AssistantMessage: 'intent.observed', PublicMessage: 'intent.observed',
+});
+const TOOLS = new Map([
+  ['read', 'read'], ['read_file', 'read'], ['readfile', 'read'],
+  ['write', 'write'], ['write_file', 'write'], ['writefile', 'write'],
+  ['edit', 'edit'], ['multiedit', 'edit'], ['apply_patch', 'edit'],
+  ['bash', 'shell'], ['exec_command', 'shell'], ['execute_bash', 'shell'],
+  ['shell', 'shell'], ['terminal', 'shell'], ['test', 'test'],
+  ['grep', 'search'], ['glob', 'search'], ['search', 'search'],
+  ['webfetch', 'other'], ['websearch', 'other'],
+]);
+const boundedString = (value, max = 1024) => typeof value === 'string' && value.length <= max ? value : '';
+const safeIdentity = (value, prefix, ...scope) => isId(value) ? value : opaque(prefix, ...scope, boundedString(value));
+function safeTime(value) {
+  const time = typeof value === 'number' ? value
+    : typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(value) ? Date.parse(value) : NaN;
+  return Number.isFinite(time) && time >= 0 && time <= 8640000000000000 ? new Date(time).toISOString() : '1970-01-01T00:00:00.000Z';
+}
+
+export function metadataEvent(event = {}) {
+  const projectId = safeIdentity(event.projectId, 'project');
+  const sessionId = safeIdentity(event.sessionId, 'session', projectId);
+  return freeze({
+    schemaVersion: 1,
+    id: safeIdentity(event.id, 'event', projectId, sessionId),
+    projectId, sessionId,
+    agentId: safeIdentity(event.agentId, 'agent', projectId, sessionId),
+    toolCallId: event.toolCallId == null ? null : safeIdentity(event.toolCallId, 'call', projectId, sessionId),
+    kind: KINDS.includes(event.kind) ? event.kind : 'capture.gap',
+    toolCategory: CATEGORIES.includes(event.toolCategory) ? event.toolCategory : 'other',
+    outcome: OUTCOMES.includes(event.outcome) ? event.outcome : 'unresolved',
+    at: safeTime(event.at),
+    sequence: integer(event.sequence) ? event.sequence : 0,
+    incomplete: event.incomplete !== false,
+  });
+}
+
+export function normalizeHostEvent(raw, { host = 'claude', projectId = '', sequence = 0, now = Date.now() } = {}) {
+  let incomplete = false;
+  if (typeof raw === 'string') {
+    if (raw.length > LIMITS.rawChars) { raw = {}; incomplete = true; }
+    else { try { raw = JSON.parse(raw); } catch { raw = {}; incomplete = true; } }
+  }
+  if (!plain(raw)) { raw = {}; incomplete = true; }
+  host = ['claude', 'codex', 'kiro'].includes(host) ? host : 'unknown';
+  projectId = safeIdentity(projectId, 'project');
+  const sessionId = opaque('session', projectId, host, boundedString(raw.session_id ?? raw.sessionId));
+  const agentId = opaque('agent', sessionId, boundedString(raw.agent_id ?? raw.agentId) || 'root');
+  const call = boundedString(raw.tool_use_id ?? raw.tool_call_id ?? raw.toolCallId);
+  const toolCallId = call ? opaque('call', sessionId, agentId, call) : null;
+  const sourceKind = boundedString(raw.hook_event_name ?? raw.event_type ?? raw.type ?? raw.kind, 80);
+  let kind = EVENTS[sourceKind] ?? (KINDS.includes(sourceKind) ? sourceKind : 'capture.gap');
+  // Delta/batch reconstruction is deliberately outside the first adapter's coverage.
+  if (raw.delta !== undefined || raw.batch_index !== undefined || raw.batchIndex !== undefined ||
+      /(?:delta|batch)/i.test(sourceKind)) kind = 'capture.gap';
+  const input = plain(raw.tool_input) ? raw.tool_input : plain(raw.input) ? raw.input : {};
+  const result = plain(raw.tool_response) ? raw.tool_response : plain(raw.result) ? raw.result : {};
+  const status = raw.outcome ?? result.status;
+  if (kind === 'tool.succeeded') {
+    if (status === 'denied') kind = 'tool.denied';
+    else if (status === 'interrupted' || status === 'cancelled' || result.interrupted === true) kind = 'tool.interrupted';
+    else if (status === 'failed' || result.is_error === true || raw.is_error === true ||
+      result.success === false || (Number.isInteger(result.exit_code) && result.exit_code !== 0)) kind = 'tool.failed';
+    else if (host !== 'claude' && status !== 'succeeded' && result.success !== true && result.exit_code !== 0) kind = 'tool.unresolved';
+  }
+  if (kind === 'capture.gap') incomplete = true;
+  const toolCategory = TOOLS.get(boundedString(raw.tool_name ?? raw.toolName, 100).toLowerCase()) ?? 'other';
+  let outcome = 'observed';
+  if (kind.startsWith('tool.')) outcome = kind === 'tool.requested' ? 'pending' : kind.slice(5);
+  if (kind === 'capture.gap') outcome = 'unresolved';
+  const paths = new Set();
+  function add(value) {
+    if (paths.size < LIMITS.paths && typeof value === 'string' && value.length > 0 && value.length <= 4096 && !/[\0\r\n]/.test(value)) paths.add(value);
+  }
+  if (kind !== 'capture.gap') {
+    // Returned filenames take priority over input directories and are only hints
+    // for a fresh EvidenceStore capture, never source evidence from tool output.
+    if (kind === 'tool.succeeded') for (const value of toolResultPaths(result, { toolCategory, input })) add(value);
+    for (const value of [input.file_path, input.path]) add(value);
+    for (const key of ['paths', 'files', 'changed_files']) {
+      if (Array.isArray(input[key])) for (const value of input[key].slice(0, LIMITS.paths)) add(plain(value) ? value.path ?? value.file_path : value);
+    }
+    const patch = boundedString(input.patch ?? input.input, LIMITS.rawChars);
+    if (toolCategory === 'edit') for (const match of patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File: ([^\r\n]+)$/gm)) add(match[1]);
+  }
+  const publicText = ['intent.observed', 'turn.prompted'].includes(kind)
+    ? boundedString(raw.publicText ?? raw.prompt ?? raw.text ?? raw.message?.text, LIMITS.snippetChars * 4) || null : null;
+  const sourceId = boundedString(raw.event_id ?? raw.id ?? raw.message_id);
+  const id = opaque('event', projectId, sessionId, agentId, sourceId || toolCallId || sequence, kind, outcome);
+  const timestamp = typeof now === 'function' ? now() : now;
+  const event = metadataEvent({
+    id, projectId, sessionId, agentId, toolCallId, kind, toolCategory, outcome,
+    at: timestamp, sequence, incomplete: incomplete || raw.incomplete === true,
+  });
+  return { event, paths: [...paths], publicText };
+}

package/runtime/core/tool-discovery.mjs

@@ -0,0 +1,122 @@
+import path from 'node:path';
+import { LIMITS, plain } from './common.mjs';
+
+const MAX_OUTPUT_CHARS = 64 * 1024;
+const MAX_OUTPUT_LINES = 256;
+
+const pathValue = value => typeof value === 'string' && value.length > 0 && value.length <= 4096 &&
+  !/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(value);
+
+function filePath(value) {
+  if (!plain(value)) return value;
+  return value.filePath ?? value.file_path ?? value.path ?? value.filename ??
+    (typeof value.file === 'string' ? value.file : undefined);
+}
+
+// This recognizes a small command grammar; it never executes or expands shell
+// text. A plain grep exclusion only removes listing lines. Other compound
+// commands and output transformations are intentionally omitted.
+function listingCommand(command) {
+  if (typeof command !== 'string' || command.length > 8192) return null;
+  const filter = /\s*\|\s*(?:(?:\/usr)?\/bin\/)?grep\s+-v\s+(?:"[A-Za-z0-9_./][A-Za-z0-9_./-]*"|'[A-Za-z0-9_./][A-Za-z0-9_./-]*'|[A-Za-z0-9_./][A-Za-z0-9_./-]*)\s*$/.exec(command);
+  if (filter) command = command.slice(0, filter.index);
+  if (/[\u0000-\u001f\u007f`$\\;&|<>#]/.test(command)) return null;
+  command = command.trim();
+  const word = /\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))(?=\s|$)/y;
+  const words = [];
+  let offset = 0;
+  while (offset < command.length && words.length < 128) {
+    word.lastIndex = offset;
+    const match = word.exec(command);
+    if (!match) return null;
+    words.push(match[1] ?? match[2] ?? match[3]);
+    offset = word.lastIndex;
+  }
+  if (offset !== command.length) return null;
+  const program = /^(?:(?:\/usr)?\/bin\/|\/opt\/homebrew\/bin\/)?(ls|find|rg)$/.exec(words.shift() ?? '')?.[1];
+  if (!program) return null;
+
+  if (program === 'ls') {
+    const operands = [];
+    let options = true;
+    for (const value of words) {
+      if (options && value === '--') { options = false; continue; }
+      if (options && value.startsWith('-')) {
+        if (!/^-[1aAF]+$/.test(value) && value !== '--color=never') return null;
+      } else {
+        if (!value || /[*?[\]{}]/.test(value)) return null;
+        operands.push(value);
+      }
+    }
+    // Multiple directory listings have headings and ambiguous relative names.
+    if (operands.length > 1) return null;
+    const operand = operands[0] ?? '.';
+    return { prefix: operand, operand };
+  }
+
+  if (program === 'find') {
+    let predicates = false;
+    for (let index = 0; index < words.length; index++) {
+      const value = words[index];
+      if (!predicates && value && !value.startsWith('-')) continue;
+      predicates = true;
+      if (['-print', '-prune', '-o', '-or', '-a', '-and', '-not', '!'].includes(value)) continue;
+      if (['-type', '-name', '-iname', '-path', '-ipath', '-maxdepth', '-mindepth'].includes(value) &&
+          typeof words[index + 1] === 'string' && words[index + 1].length > 0) { index++; continue; }
+      return null;
+    }
+    return { prefix: '.' };
+  }
+
+  if (!words.includes('--files')) return null;
+  for (let index = 0; index < words.length; index++) {
+    const value = words[index];
+    if (!value.startsWith('-') || [
+      '--files', '--hidden', '--no-ignore', '--no-ignore-vcs', '--follow',
+      '-L', '-u', '-uu', '-uuu', '--color=never', '--sort=path',
+    ].includes(value)) continue;
+    if (['-g', '--glob', '-t', '--type', '-T', '--type-not'].includes(value) &&
+        typeof words[index + 1] === 'string' && words[index + 1].length > 0) { index++; continue; }
+    if (/^(?:--glob|--type|--type-not)=.+$/.test(value)) continue;
+    return null;
+  }
+  return { prefix: '.' };
+}
+
+function looksLikeFile(value) {
+  // Whitespace, control sequences, URLs, source lines and prose are not file
+  // listings. Paths with spaces remain supported by structured result fields.
+  return pathValue(value) && /^[\p{L}\p{N}_./@+,[\]-]+$/u.test(value) &&
+    /(?:^|\/)(?:[^/]+\.[\p{L}\p{N}_-]{1,16}|Dockerfile|Containerfile|Makefile|Procfile|Gemfile|Rakefile)$/u.test(value);
+}
+
+export function toolResultPaths(result, { toolCategory, input = {} } = {}) {
+  if (!plain(result) || result.interrupted === true || result.isImage === true) return [];
+  const paths = new Set();
+  const add = value => { if (paths.size < LIMITS.paths && pathValue(value)) paths.add(value); };
+  for (const value of [result.filePath, result.file_path, result.path]) add(value);
+  if (plain(result.file)) add(filePath(result.file));
+  for (const key of ['paths', 'files', 'changed_files', 'filenames']) {
+    if (Array.isArray(result[key])) {
+      for (const value of result[key].slice(0, LIMITS.paths)) add(filePath(value));
+    }
+  }
+  if (toolCategory === 'search' && Array.isArray(result.matches)) {
+    for (const match of result.matches.slice(0, LIMITS.paths)) if (plain(match)) add(filePath(match));
+  }
+  if (toolCategory !== 'shell' || typeof result.stdout !== 'string') return [...paths];
+  const command = listingCommand(input.command ?? input.cmd);
+  if (!command) return [...paths];
+  let output = result.stdout.slice(0, MAX_OUTPUT_CHARS);
+  // Never turn a truncated fragment into a filename.
+  if (result.stdout.length > MAX_OUTPUT_CHARS) output = output.slice(0, output.lastIndexOf('\n') + 1);
+  for (const line of output.split('\n', MAX_OUTPUT_LINES)) {
+    const value = line.endsWith('\r') ? line.slice(0, -1) : line;
+    if (paths.size >= LIMITS.paths) break;
+    // ls echoes an explicit file operand. Other returned names are children of
+    // its directory operand, including directories whose names contain dots.
+    if (looksLikeFile(value)) add(value === command.operand || command.prefix === '.' || path.isAbsolute(value)
+      ? value : path.join(command.prefix, value));
+  }
+  return [...paths];
+}

package/runtime/daemon/auth.mjs

@@ -0,0 +1,50 @@
+import { randomBytes, createHash } from 'node:crypto';
+
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const secret = () => randomBytes(32).toString('base64url');
+
+export function createAuth({ origin, instanceId, now = Date.now }) {
+  const tokens = new Map(), sessions = new Map();
+  const cookieName = `graphlin_${instanceId.replaceAll('-', '').slice(0, 16)}`;
+  function prune(map) {
+    for (const [key, expires] of map) if (expires <= now()) map.delete(key);
+    while (map.size >= 16) map.delete(map.keys().next().value);
+  }
+  return {
+    cookieName,
+    validRequest(req, { mutation = false } = {}) {
+      const hosts = req.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'host');
+      if (hosts.length !== 1 || req.headers.host !== new URL(origin).host) return false;
+      if (!['127.0.0.1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress)) return false;
+      if (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(req.headers['sec-fetch-site'])) return false;
+      if (mutation) return req.headers.origin === origin;
+      return req.headers.origin === undefined || req.headers.origin === origin;
+    },
+    launchToken() {
+      prune(tokens);
+      const token = secret(); tokens.set(digest(token), now() + 60_000);
+      return token;
+    },
+    exchange(token) {
+      if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token)) return null;
+      const key = digest(token), expires = tokens.get(key);
+      tokens.delete(key);
+      if (!expires || expires <= now()) return null;
+      prune(sessions);
+      const session = secret(); sessions.set(digest(session), now() + 8 * 60 * 60 * 1000);
+      return `${cookieName}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=28800`;
+    },
+    authorized(req) {
+      const raw = req.headers.cookie;
+      if (typeof raw !== 'string' || raw.length > 8192) return false;
+      const values = raw.split(';').map((part) => part.trim()).filter((part) => part.startsWith(`${cookieName}=`));
+      if (values.length !== 1) return false;
+      const token = values[0].slice(cookieName.length + 1);
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return false;
+      const key = digest(token), expires = sessions.get(key);
+      if (!expires || expires <= now()) { sessions.delete(key); return false; }
+      return true;
+    },
+    clear() { tokens.clear(); sessions.clear(); },
+  };
+}

package/runtime/daemon/connection-info.mjs

@@ -0,0 +1,249 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PLUGIN_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+const PROFILES = new Set(['claude', 'codex', 'portable']);
+const MAX_PATH_BYTES = 4096;
+const MAX_COMMAND_BYTES = 8192;
+const MAX_MANIFEST_BYTES = 16 * 1024;
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/;
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const version = value => typeof value === 'string' && value.length <= 80 &&
+  /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/.test(value);
+const manifest = value => record(value) && value.name === 'graphlin' && version(value.version);
+
+function absolute(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || CONTROLS.test(value) ||
+      Buffer.byteLength(value) > MAX_PATH_BYTES) throw new TypeError('invalid_connection_info');
+  return path.resolve(value);
+}
+
+// A single POSIX shell argument. No caller value is treated as shell syntax.
+const quote = value => `'${value.replaceAll("'", "'\"'\"'")}'`;
+
+async function regularFile(filename) {
+  try { return (await lstat(filename)).isFile(); }
+  catch { return false; }
+}
+
+async function directory(filename) {
+  try { return (await lstat(filename)).isDirectory(); }
+  catch { return false; }
+}
+
+async function readSmall(filename, limit = MAX_MANIFEST_BYTES) {
+  let handle;
+  try {
+    // NONBLOCK avoids waiting on a substituted FIFO; NOFOLLOW rejects a linked
+    // metadata file. The handle check and bounded read also cover replacement.
+    handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > limit) return { status: 'invalid' };
+    const bytes = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length <= limit) {
+      const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    return length > limit ? { status: 'invalid' }
+      : { status: 'present', text: bytes.subarray(0, length).toString('utf8') };
+  } catch (error) {
+    return { status: error.code === 'ENOENT' ? 'missing' : 'invalid' };
+  } finally { await handle?.close(); }
+}
+
+async function json(filename) {
+  const result = await readSmall(filename);
+  try { return result.status === 'present' ? JSON.parse(result.text) : null; }
+  catch { return null; }
+}
+
+async function packageMarker(root) {
+  const result = await readSmall(path.join(root, '.graphlin-package'), 64);
+  if (result.status !== 'present') return result;
+  const profile = result.text.trim();
+  return PROFILES.has(profile) ? { status: 'present', profile } : { status: 'invalid' };
+}
+
+async function sourceCheckout(root, current) {
+  const [claude, codex, builder] = await Promise.all([
+    json(path.join(root, '.claude-plugin/plugin.json')),
+    json(path.join(root, '.codex-plugin/plugin.json')),
+    regularFile(path.join(root, 'scripts/build-packages.mjs')),
+  ]);
+  return builder && manifest(claude) && manifest(codex) &&
+    claude.version === current.version && codex.version === current.version &&
+    claude.hooks === './adapters/claude/hooks.json' &&
+    current.extensions?.['com.openai']?.hooks === './adapters/codex/hooks.json';
+}
+
+async function hostPackage(root, host, currentVersion) {
+  const [isDirectory, marker, portable, native, mcp, hooks, ...files] = await Promise.all([
+    directory(root), packageMarker(root), json(path.join(root, 'plugin.json')),
+    json(path.join(root, `.${host}-plugin/plugin.json`)),
+    json(path.join(root, '.mcp.json')),
+    json(path.join(root, `adapters/${host}/hooks.json`)),
+    ...['scripts/control.mjs', 'scripts/collect.sh', 'scripts/collector.mjs', 'runtime/collector/index.mjs']
+      .map(file => regularFile(path.join(root, file))),
+  ]);
+  const expectedRoot = host === 'claude' ? '${CLAUDE_PLUGIN_ROOT}' : '${PLUGIN_ROOT}';
+  const server = mcp?.mcpServers?.graphlin;
+  return isDirectory && marker.profile === host && manifest(portable) && manifest(native) &&
+    portable.version === currentVersion && native.version === currentVersion && files.every(Boolean) &&
+    server?.command === 'node' && Array.isArray(server.args) && server.args.length === 1 &&
+    server.args[0] === `${expectedRoot}/scripts/control.mjs` &&
+    record(hooks?.hooks) && Object.keys(hooks.hooks).length > 0 &&
+    (host === 'claude' ? native.hooks === './adapters/claude/hooks.json'
+      : native.mcpServers === './.mcp.json' &&
+        portable.extensions?.['com.openai']?.hooks === './adapters/codex/hooks.json');
+}
+
+async function localMarketplace(root, codexRoot) {
+  const value = await json(path.join(root, '.agents/plugins/marketplace.json'));
+  if (!record(value) || value.name !== 'graphlin-local' || !Array.isArray(value.plugins)) return false;
+  const entries = value.plugins.filter(entry => entry?.name === 'graphlin');
+  if (entries.length !== 1) return false;
+  const entry = entries[0];
+  return entry.source?.source === 'local' && entry.source.path === './graphlin' &&
+    path.join(root, 'graphlin') === codexRoot &&
+    entry.policy?.installation === 'AVAILABLE' && entry.policy?.authentication === 'ON_INSTALL';
+}
+
+export async function inspectInstalledPackages({ dataDir, version: currentVersion }) {
+  if (!version(currentVersion)) return { claude: false, codex: false };
+  const root = path.join(absolute(dataDir), 'plugins', 'graphlin', currentVersion);
+  const [claude, codex] = await Promise.all(['claude', 'codex'].map(host =>
+    hostPackage(path.join(root, host, 'graphlin'), host, currentVersion)));
+  return { claude, codex };
+}
+
+// Discovery reads only fixed package metadata and checks file availability.
+// It never scans the project, reads state/credentials, or executes commands.
+async function discover(pluginRoot, dataDir) {
+  const [marker, current, isDirectory] = await Promise.all([
+    packageMarker(pluginRoot), json(path.join(pluginRoot, 'plugin.json')), directory(pluginRoot),
+  ]);
+  if (!isDirectory || !manifest(current) || marker.status === 'invalid') return { available: false };
+  if (marker.status === 'missing') {
+    if (!await sourceCheckout(pluginRoot, current)) return { available: false };
+    // npm installations can be read-only. Generated host packages belong in
+    // the same user-owned data directory as the running service, not beside
+    // installed code. Versioned paths stay stable across projects and restarts.
+    const output = path.join(dataDir, 'plugins', 'graphlin', current.version);
+    const claudeRoot = path.join(output, 'claude/graphlin');
+    const codexRoot = path.join(output, 'codex/graphlin');
+    const [claudeReady, codexReady, marketplaceReady] = await Promise.all([
+      hostPackage(claudeRoot, 'claude', current.version),
+      hostPackage(codexRoot, 'codex', current.version),
+      localMarketplace(path.dirname(codexRoot), codexRoot),
+    ]);
+    return {
+      available: true,
+      ...(claudeReady && codexReady && marketplaceReady ? {} : { build: path.join(pluginRoot, 'scripts/build-packages.mjs') }),
+      output,
+      claude: claudeRoot,
+      marketplace: path.join(output, 'codex'),
+    };
+  }
+  const distribution = path.resolve(pluginRoot, '../..');
+  const claudeRoot = marker.profile === 'claude' ? pluginRoot : path.join(distribution, 'claude/graphlin');
+  const codexRoot = marker.profile === 'codex' ? pluginRoot : path.join(distribution, 'codex/graphlin');
+  const marketplaceRoot = path.dirname(codexRoot);
+  const [claude, codex, marketplace] = await Promise.all([
+    hostPackage(claudeRoot, 'claude', current.version),
+    hostPackage(codexRoot, 'codex', current.version),
+    localMarketplace(marketplaceRoot, codexRoot),
+  ]);
+  return {
+    available: true, claude: claude ? claudeRoot : null,
+    marketplace: codex && marketplace ? marketplaceRoot : null,
+  };
+}
+
+function format({ projectRoot, dataDir, mode }, found) {
+  const result = { projectRoot, mode, instructions: [], notes: [] };
+  if (mode === 'demo') {
+    result.notes.push('This viewer is in demo mode and uses fixture classifications. Open a live Graphlin viewer for your own project before connecting your work.');
+  }
+  if (!found.available) {
+    result.notes.push('Connection setup is unavailable because this Graphlin source checkout or package could not be verified. Obtain a complete Graphlin distribution.');
+    return result;
+  }
+  const terminal = words => `cd ${quote(projectRoot)} && GRAPHLIN_DATA_DIR=${quote(dataDir)} ${words}`;
+  const instruction = (id, title, description, steps) => ({ id, title, description, steps });
+  const fits = entries => entries.every(item => item.steps.every(step =>
+    Buffer.byteLength(step.command) <= MAX_COMMAND_BYTES));
+  function append(entries, host) {
+    if (fits(entries)) result.instructions.push(...entries);
+    else result.notes.push(`${host} commands are too long to display safely. Use shorter project, package, or data directory paths.`);
+  }
+
+  if (found.build) {
+    const build = [instruction('build-packages', 'Build current plugin packages',
+      'Run this prerequisite first. It rebuilds both host profiles in your Graphlin data directory; existing generated packages may be out of date.',
+      [{ label: 'Build packages in Terminal', command: terminal(`node ${quote(found.build)} --out ${quote(found.output)}`) }])];
+    if (!fits(build)) {
+      result.notes.push('The build command is too long to display safely. Use shorter project, package, or data directory paths.');
+      return result;
+    }
+    result.instructions.push(...build);
+  }
+  const prerequisite = found.build ? 'Complete the build step above first. ' : '';
+  if (found.claude) {
+    const launch = terminal(`claude --plugin-dir ${quote(found.claude)}`);
+    append([
+      instruction('claude-new', 'Claude: new session',
+        `${prerequisite}Start a new Claude session with this Graphlin plugin loaded.`,
+        [{ label: 'Start Claude in Terminal', command: launch }]),
+      instruction('claude-resume', 'Claude: resume',
+        `${prerequisite}Instead of starting a new session, continue the most recent conversation in this project.`,
+        [{ label: 'Resume Claude in Terminal', command: `${launch} --continue` }]),
+    ], 'Claude');
+  } else {
+    result.notes.push('Claude connection is unavailable: matching packaged files were not found. Rebuild or obtain the complete Graphlin distribution, including its Claude profile.');
+  }
+  if (found.marketplace) {
+    const hooks = () => ({
+      label: 'Inside Codex: /hooks', command: '/hooks',
+      description: 'Inside Codex, review and trust Graphlin hooks; then start your work',
+    });
+    const launch = terminal(`codex -C ${quote(projectRoot)}`);
+    append([
+      instruction('codex-setup', 'Codex: install the local plugin',
+        `${prerequisite}Run both setup commands before launching. They register this local marketplace and install its Graphlin package in Codex.`,
+        [
+          { label: 'Register marketplace in Terminal', command: terminal(`codex plugin marketplace add ${quote(found.marketplace)}`) },
+          { label: 'Install Graphlin in Terminal', command: terminal(`codex plugin add ${quote('graphlin@graphlin-local')}`) },
+        ]),
+      instruction('codex-new', 'Codex: new session',
+        'Complete Codex setup above, then start a new session and review the hooks inside Codex.',
+        [{ label: 'Start Codex in Terminal', command: launch }, hooks()]),
+      instruction('codex-resume', 'Codex: resume',
+        'Complete Codex setup above. Instead of starting a new session, resume the most recent conversation in this project.',
+        [{ label: 'Resume Codex in Terminal', command: `${launch} resume --last` }, hooks()]),
+    ], 'Codex');
+  } else {
+    result.notes.push('Codex connection is unavailable: matching packaged files and a valid local marketplace were not found. Rebuild or obtain the complete Graphlin distribution, including its Codex marketplace.');
+  }
+  result.notes.push('Choose either a new session or resume. Keep the Graphlin viewer running while you work.');
+  result.notes.push('Package discovery does not confirm that host hooks are active. Follow the host prompts to load and trust the plugin.');
+  return result;
+}
+
+/**
+ * Read-only connection instructions for an authenticated local endpoint.
+ * All inputs must come from the daemon's trusted startup context, not a request
+ * body/query. projectRoot and dataDir are already canonicalized by projectPaths.
+ * No environment, graph, launch URL, or credential is copied into the result.
+ */
+export async function createConnectionInfo({
+  projectRoot, dataDir, mode = 'live', pluginRoot = PLUGIN_ROOT,
+} = {}) {
+  if (!['live', 'demo'].includes(mode)) throw new TypeError('invalid_connection_info');
+  const context = { projectRoot: absolute(projectRoot), dataDir: absolute(dataDir), mode };
+  const root = absolute(pluginRoot);
+  return format(context, await discover(root, context.dataDir));
+}