forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/commands/gate.js

@@ -21,12 +21,13 @@
  */
 
 const path = require('node:path');
+const { stripGlobalFlags } = require('../global-flags');
 const { setConfigOverride } = require('../config-writer');
 const { getDefaultRuntimeGraph, getResolvedRuntimeGraph } = require('../core/runtime-graph');
 const {
   recordGateEvent,
   listGateEvents,
-  isGateApproved,
+  evaluateGateApproval,
 } = require('../gate-events');
 
 // The doc-update gate folds under this noun as `gate doc` (P2, kernel issue
@@ -38,14 +39,138 @@ const docGate = require('./doc-gate');
 
 const TOGGLE_ACTIONS = new Set(['enable', 'disable']);
 const EVENT_ACTIONS = new Set(['approve', 'reject', 'status', 'check']);
+const MAX_GATE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const GATE_JSON_SCHEMA = 'forge.gate.v1';
 
 function usage() {
   return [
-    'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--reason <text>] [--json]',
+    'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--ttl <duration>] [--reason <text>] [--json]',
     '       forge gate doc <detect|check|init|okf|...> [args]   (doc-update gate; = forge doc-gate, run `forge doc-gate --help`)',
   ].join('\n');
 }
 
+function parseGateTtl(raw, issuedAt) {
+  if (raw === undefined) return { ok: true, expiresAt: null, requestIdentity: null };
+  const match = /^(\d+)(s|m|h|d)$/.exec(String(raw));
+  if (!match) return { ok: false, error: 'TTL must be a positive duration such as 30s, 5m, 2h, or 1d.' };
+  const multipliers = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  const ttlMs = Number(match[1]) * multipliers[match[2]];
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > MAX_GATE_TTL_MS) {
+    return { ok: false, error: 'TTL must be greater than zero and no more than 30d.' };
+  }
+  const issuedMillis = Date.parse(issuedAt);
+  if (!Number.isFinite(issuedMillis)) return { ok: false, error: 'Cannot issue a TTL approval without a valid clock.' };
+  const expiresMillis = issuedMillis + ttlMs;
+  if (!Number.isFinite(expiresMillis)) return { ok: false, error: 'TTL expiry is outside the supported date range.' };
+  const expiryDate = new Date(expiresMillis);
+  if (!Number.isFinite(expiryDate.getTime())) {
+    return { ok: false, error: 'TTL expiry is outside the supported date range.' };
+  }
+  return {
+    ok: true,
+    expiresAt: expiryDate.toISOString(),
+    requestIdentity: `ttl-ms=${ttlMs}`,
+  };
+}
+
+function parseDecisionInput(action, rawArgs, flags) {
+  const issueId = rawArgs[0];
+  const gateId = rawArgs[1];
+  if (!issueId || !gateId || issueId.startsWith('--') || gateId.startsWith('--')) {
+    return { ok: false, error: `Missing issue id or gate id.\n${usage()}` };
+  }
+  if (flags.project !== undefined || flags['--project'] !== undefined) {
+    return { ok: false, error: 'Gate approvals are issue-scoped; --project is not supported.' };
+  }
+
+  let ttl = flags.ttl ?? flags['--ttl'];
+  let reason = flags.reason ?? flags['--reason'];
+  const seen = new Set();
+  for (let index = 2; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index];
+    if (token === '--json') {
+      if (seen.has('json')) return { ok: false, error: 'Duplicate --json flag.' };
+      seen.add('json');
+      continue;
+    }
+    const match = /^(--ttl|--reason)(?:=(.*))?$/.exec(token);
+    if (!match) {
+      const kind = token.startsWith('--') ? 'Unknown flag' : 'Unexpected argument';
+      return { ok: false, error: `${kind} '${token}'.\n${usage()}` };
+    }
+    const name = match[1].slice(2);
+    if (seen.has(name)) return { ok: false, error: `Duplicate --${name} flag.` };
+    seen.add(name);
+    let value = match[2];
+    if (value === undefined) {
+      value = rawArgs[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        return { ok: false, error: `--${name} requires a value.` };
+      }
+      index += 1;
+    }
+    if (name === 'ttl') ttl = value;
+    if (name === 'reason') reason = value;
+  }
+  if (action !== 'approve' && ttl !== undefined) {
+    return { ok: false, error: '--ttl is valid only for gate approval.' };
+  }
+  return { ok: true, issueId, gateId, ttl, reason };
+}
+
+function parseReadInput(action, rawArgs) {
+  const operandCount = action === 'status' ? 1 : 2;
+  const issueId = rawArgs[0];
+  const gateId = operandCount === 2 ? rawArgs[1] : undefined;
+  if (!issueId || issueId.startsWith('--') || (operandCount === 2 && (!gateId || gateId.startsWith('--')))) {
+    const missing = action === 'status' ? 'issue id' : 'issue id or gate id';
+    return { ok: false, error: `Missing ${missing}.\n${usage()}` };
+  }
+
+  let jsonSeen = false;
+  for (const token of rawArgs.slice(operandCount)) {
+    if (token === '--json') {
+      if (jsonSeen) return { ok: false, error: 'Duplicate --json flag.' };
+      jsonSeen = true;
+      continue;
+    }
+    const kind = token.startsWith('--') ? 'Unknown flag' : 'Unexpected argument';
+    return { ok: false, error: `${kind} '${token}'.\n${usage()}` };
+  }
+  return { ok: true, issueId, gateId };
+}
+
+function gateJsonResult(action, result, context = {}) {
+  const event = result.event ?? null;
+  const envelope = {
+    schema_version: GATE_JSON_SCHEMA,
+    command: `gate.${action}`,
+    ok: result.success === true,
+    issue_id: event?.issue_id ?? result.issueId ?? context.issueId ?? null,
+  };
+  const gateId = event?.gate ?? context.gateId;
+  if (action !== 'status' && gateId !== undefined && gateId !== null) {
+    envelope.gate_id = gateId;
+  }
+  if (action === 'approve' || action === 'reject') {
+    envelope.duplicate = result.duplicate === true;
+    envelope.decision = event?.decision ?? (action === 'approve' ? 'approved' : 'rejected');
+    envelope.event = event;
+  }
+  if (action === 'status') {
+    envelope.issue = envelope.issue_id;
+    envelope.events = result.events ?? [];
+  }
+  if (action === 'check') {
+    envelope.approved = result.approved === true;
+    envelope.satisfied = result.success === true;
+    envelope.disabled = result.disabled === true;
+    envelope.event = event;
+  }
+  if (result.error) envelope.error = result.error;
+  return { ...result, output: JSON.stringify(envelope, null, 2) };
+}
+
 // The known-toggle set is gates PLUS unlocked toggleable rails (e.g.
 // rail.kernel_tracking): both are governed through the same `forge gate
 // enable|disable` surface and the resolver's rail-aware workflow.gates loop.
@@ -96,22 +221,27 @@ function handleToggle(action, gateId, projectRoot) {
   };
 }
 
-async function handleDecision(action, issueId, gateId, flags, projectRoot, opts) {
-  if (!issueId || !gateId) {
-    return { success: false, error: `Missing issue id or gate id.\n${usage()}` };
-  }
+async function handleDecision(action, input, projectRoot, opts) {
+  if (!input.ok) return { success: false, error: input.error };
+  const { issueId, gateId } = input;
   const known = validateKnownGate(gateId);
   if (!known.ok) return { success: false, error: known.error };
 
   const decision = action === 'approve' ? 'approved' : 'rejected';
-  const reason = typeof flags.reason === 'string' ? flags.reason : undefined;
+  const reason = typeof input.reason === 'string' ? input.reason : undefined;
+  const issuedAt = opts.now || new Date().toISOString();
+  const expiry = parseGateTtl(input.ttl, issuedAt);
+  if (!expiry.ok) return { success: false, error: expiry.error };
   const result = await recordGateEvent(projectRoot, {
     issueId,
     gateId,
     decision,
     reason,
+    expiresAt: expiry.expiresAt,
+    requestIdentity: expiry.requestIdentity,
     env: opts.env,
     deps: kernelDeps(opts),
+    now: issuedAt,
   });
 
   if (result.issueMissing) {
@@ -125,29 +255,26 @@ async function handleDecision(action, issueId, gateId, flags, projectRoot, opts)
     success: true,
     duplicate: result.duplicate === true,
     actor: result.actor,
-    output: `${verb} gate '${gateId}' for ${issueId} (actor ${result.actor})${reasonNote}${suffix}`,
+    event: result.event,
+    output: `${verb} gate '${gateId}' for ${issueId} (control ${result.event.control_id}; actor ${result.actor}; issued ${result.event.issued_at}; expires ${result.event.expires_at || 'never'})${reasonNote}${suffix}`,
   };
 }
 
-async function handleStatus(issueId, flags, projectRoot, opts) {
+async function handleStatus(issueId, _flags, projectRoot, opts) {
   if (!issueId) {
     return { success: false, error: `Missing issue id.\n${usage()}` };
   }
   const events = await listGateEvents(projectRoot, issueId, { deps: kernelDeps(opts) });
 
-  if (flags.json) {
-    return { success: true, output: JSON.stringify({ issue: issueId, events }, null, 2) };
-  }
-
   if (events.length === 0) {
-    return { success: true, output: `No gate events for ${issueId}.` };
+    return { success: true, issueId, events, output: `No gate events for ${issueId}.` };
   }
   const lines = events.map(event => {
     const label = event.event_type === 'gate.approved' ? 'APPROVED' : 'REJECTED';
     const reason = event.reason ? ` — ${event.reason}` : '';
-    return `${label} ${event.gate} by ${event.actor} at ${event.created_at}${reason}`;
+    return `${label} ${event.gate} for ${event.issue_id} (${event.control_id}) by ${event.actor} at ${event.issued_at}; expires ${event.expires_at || 'never'}${reason}`;
   });
-  return { success: true, output: `Gate events for ${issueId}:\n${lines.join('\n')}` };
+  return { success: true, issueId, events, output: `Gate events for ${issueId}:\n${lines.join('\n')}` };
 }
 
 async function handleCheck(issueId, gateId, projectRoot, opts) {
@@ -162,18 +289,42 @@ async function handleCheck(issueId, gateId, projectRoot, opts) {
   const resolved = getResolvedRuntimeGraph({ projectRoot });
   const resolvedGate = [...resolved.gates, ...resolved.rails].find(gate => gate.id === gateId);
   if (resolvedGate && resolvedGate.enabled === false) {
-    return { success: true, output: `gate ${gateId} is disabled — satisfied for ${issueId}` };
+    return {
+      success: true,
+      issueId,
+      approved: false,
+      disabled: true,
+      output: `gate ${gateId} is disabled — satisfied for ${issueId}`,
+    };
   }
 
-  const approved = await isGateApproved(projectRoot, issueId, gateId, { deps: kernelDeps(opts) });
-  if (approved) {
-    return { success: true, output: `gate ${gateId} approved for ${issueId}` };
+  const events = await listGateEvents(projectRoot, issueId, { deps: kernelDeps(opts) });
+  const decision = evaluateGateApproval(events, gateId, opts.now);
+  const event = decision.event;
+  if (decision.approved) {
+    return {
+      success: true,
+      event,
+      approved: true,
+      output: `gate ${gateId} approved for ${issueId} (control ${event.control_id}; actor ${event.actor}; decision ${event.decision}; issued ${event.issued_at}; expires ${event.expires_at || 'never'})`,
+    };
   }
-  return { success: false, error: `gate ${gateId} not approved for ${issueId}` };
+  const evidence = event
+    ? ` (control ${event.control_id}; actor ${event.actor}; decision ${event.decision}; issued ${event.issued_at}; expires ${event.expires_at || 'never'})`
+    : '';
+  return {
+    success: false,
+    event,
+    issueId,
+    approved: false,
+    error: `gate ${gateId} not approved for ${issueId}${evidence}`,
+  };
 }
 
 async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
-  const [action, ...rest] = args;
+  const normalizedArgs = stripGlobalFlags(args);
+  const [action, ...rest] = normalizedArgs;
+  const wantsJson = flags.json === true || flags['--json'] === true || normalizedArgs.includes('--json');
 
   // `gate doc [<doc-gate sub> ...]` → the standalone doc-gate handler, with the
   // consumed `doc` token dropped so its own arg shape (detect/check/init/okf …)
@@ -186,13 +337,28 @@ async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {})
     return handleToggle(action, rest[0], projectRoot);
   }
   if (EVENT_ACTIONS.has(action)) {
+    let result;
+    let input;
     if (action === 'status') {
-      return handleStatus(rest[0], flags, projectRoot, opts);
-    }
-    if (action === 'check') {
-      return handleCheck(rest[0], rest[1], projectRoot, opts);
+      input = parseReadInput(action, rest);
+      result = input.ok
+        ? await handleStatus(input.issueId, flags, projectRoot, opts)
+        : { success: false, issueId: rest[0], error: input.error };
+    } else if (action === 'check') {
+      input = parseReadInput(action, rest);
+      result = input.ok
+        ? await handleCheck(input.issueId, input.gateId, projectRoot, opts)
+        : { success: false, issueId: rest[0], approved: false, error: input.error };
+    } else {
+      input = parseDecisionInput(action, rest, flags);
+      result = await handleDecision(action, input, projectRoot, opts);
     }
-    return handleDecision(action, rest[0], rest[1], flags, projectRoot, opts);
+    const context = input.ok
+      ? { issueId: input.issueId, ...(input.gateId ? { gateId: input.gateId } : {}) }
+      : { issueId: rest[0] };
+    return wantsJson
+      ? gateJsonResult(action, result, context)
+      : result;
   }
 
   return {
@@ -206,4 +372,8 @@ module.exports = {
   description: 'Toggle a workflow gate, or record/query human-gate approval events',
   usage: usage(),
   handler,
+  parseGateTtl,
+  parseDecisionInput,
+  parseReadInput,
+  gateJsonResult,
 };

package/lib/commands/github.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const { constants } = require('node:os');
+const spawn = require('cross-spawn');
+const {
+  createGithubContext, prepareGithubAccount, readGithubAccount,
+  writeGithubAccount, unsetGithubAccount, validateGithubLogin,
+} = require('../github-context');
+const { stripGlobalFlags } = require('../global-flags');
+const { defaultResolveLocalRepository } = require('./merge');
+
+const usage = 'forge github use <login> | status [--json] | unset | run -- <program> [args...]';
+const ERROR_MESSAGES = {
+  INVALID_GITHUB_LOGIN: 'GitHub login must be 1-39 letters, numbers, or internal hyphens.',
+  GIT_CONFIG_FAILED: 'Unable to access this clone-local GitHub account binding.',
+  GITHUB_NOT_AUTHENTICATED: 'Account is not authenticated. Run gh auth login --hostname github.com for the account, then retry.',
+  GITHUB_AUTH_FAILED: 'Unable to verify the account. Run gh auth login --hostname github.com, then retry.',
+  GITHUB_CLI_UNSUPPORTED: 'Upgrade GitHub CLI to support gh auth token --hostname github.com --user <login>.',
+  GITHUB_ACCOUNT_MISMATCH: 'The authenticated GitHub account does not match this clone binding.',
+  GITHUB_COMMAND_FAILED: 'The selected account cannot view this repository. Check repository permissions and organization SSO.',
+  GITHUB_REPOSITORY_INVALID: 'Origin must identify a GitHub.com repository. Check its URL and SSH alias configuration.',
+};
+
+function safeFailure(error) {
+  const code = Object.hasOwn(ERROR_MESSAGES, error?.code) ? error.code : 'GITHUB_OPERATION_FAILED';
+  return { success: false, code, error: ERROR_MESSAGES[code] || 'GitHub account operation failed. Run forge github status for diagnostics.' };
+}
+
+function isGithubOrigin(remote, root, options) {
+  try {
+    const scpHost = /^[A-Za-z]:/.test(remote) || /^(?:git|https?|ssh|file):/i.test(remote) ? null
+      : /^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9][A-Za-z0-9._-]*):[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?$/.exec(remote);
+    const parsed = scpHost ? null : new URL(remote);
+    if (parsed && !['https:', 'ssh:'].includes(parsed.protocol)) return false;
+    const host = scpHost ? scpHost[1] : parsed.hostname;
+    if (host.toLowerCase() === 'github.com') return true;
+    if ((!scpHost && parsed.protocol !== 'ssh:') || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(host)) return false;
+    // Resolve configured SSH aliases locally; -G does not open a connection.
+    const run = options.runner || execFileSync;
+    const config = String(run('ssh', ['-G', host], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 3000,
+    }));
+    return /^hostname\s+github\.com\s*$/im.test(config);
+  } catch { return false; }
+}
+
+function repositoryAccess(context, root, options) {
+  const remote = readGit(root, ['remote', 'get-url', 'origin'], options);
+  const repository = defaultResolveLocalRepository({ projectRoot: root, git: () => remote });
+  if (!repository || !isGithubOrigin(remote, root, options)) {
+    throw Object.assign(new Error(ERROR_MESSAGES.GITHUB_REPOSITORY_INVALID), { code: 'GITHUB_REPOSITORY_INVALID' });
+  }
+  context.runGh(['repo', 'view', `github.com/${repository}`, '--json', 'nameWithOwner'], { cwd: root, timeout: 30000 });
+}
+
+function readGit(root, args, options) {
+  try {
+    const run = options.runner || execFileSync;
+    return String(run('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 3000 }) || '').trim();
+  } catch { return ''; }
+}
+
+function boundedText(value) {
+  // Author fields are display data, never terminal control sequences.
+  return value.replace(/\p{Cc}/gu, '').slice(0, 160) || null;
+}
+
+function transportOf(remote) {
+  if (!remote) return 'missing';
+  if (/^https:\/\//i.test(remote)) return 'https';
+  if (/^http:\/\//i.test(remote)) return 'http';
+  if (/^ssh:\/\//i.test(remote)
+    || (!/^[A-Za-z]:/.test(remote) && !/^(?:git|https?|ssh|file):/i.test(remote)
+      && /^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9][A-Za-z0-9._-]*:[^\\/\s][^\s]*$/.test(remote))) return 'ssh';
+  return 'other';
+}
+
+function helperOf(helper) {
+  if (!helper) return 'none';
+  if (/\bgh(?:\.exe)?\s+auth\s+git-credential\b/i.test(helper)) return 'github-cli';
+  if (/\bmanager(?:-core)?\b/i.test(helper)) return 'credential-manager';
+  return 'other';
+}
+
+function localDiagnostics(root, options) {
+  return {
+    author: {
+      name: boundedText(readGit(root, ['config', '--get', 'user.name'], options)),
+      email: boundedText(readGit(root, ['config', '--get', 'user.email'], options)),
+    },
+    transport: transportOf(readGit(root, ['remote', 'get-url', 'origin'], options)),
+    credentialHelper: helperOf(readGit(root, ['config', '--get-all', 'credential.helper'], options)),
+  };
+}
+
+function renderStatus(status) {
+  const lines = [
+    `GitHub: ${status.state}`,
+    `Clone account: ${status.account || 'not selected'}`,
+    `Verified login: ${status.login || 'unavailable'}`,
+    `Commit author: ${status.author.name || 'unset'} <${status.author.email || 'unset'}>`,
+    `Origin transport: ${status.transport}; credential helper: ${status.credentialHelper}`,
+  ];
+  if (status.error) lines.push(status.error);
+  if (status.state === 'unbound') lines.push('Optional: authenticate with gh auth login, then select an account with forge github use <login>.');
+  if (status.transport === 'ssh') lines.push('SSH key selection is controlled by your SSH configuration.');
+  if (status.transport === 'https' && status.credentialHelper === 'github-cli') {
+    lines.push('HTTPS uses the GitHub CLI helper; a launched session may also use its selected token for Git transport.');
+  } else if (status.transport === 'https') {
+    lines.push('HTTPS Git credentials are selected separately by your credential helper.');
+  }
+  return lines.join('\n');
+}
+
+function accountStatus(root, options) {
+  const status = { state: 'unbound', account: null, source: null, login: null, repositoryAccess: null, ...localDiagnostics(root, options) };
+  try {
+    const account = readGithubAccount(root, options);
+    if (!account) return status;
+    status.source = 'clone-local';
+    status.account = validateGithubLogin(account) ? account : null;
+    const context = prepareGithubAccount(root, account, options);
+    status.login = context.login;
+    status.repositoryAccess = false;
+    repositoryAccess(context, root, options);
+    status.repositoryAccess = true;
+    status.state = 'ready';
+  } catch (error) {
+    const failure = safeFailure(error);
+    status.state = status.login ? 'no_repository_access' : 'unauthenticated';
+    if (failure.code === 'GITHUB_ACCOUNT_MISMATCH') {
+      status.state = 'mismatch';
+      const match = /^GitHub account mismatch: expected [A-Za-z0-9-]+, received ([A-Za-z0-9-]+)\.$/.exec(error.message);
+      status.login = match && validateGithubLogin(match[1]) ? match[1] : null;
+    }
+    status.code = failure.code;
+    status.error = failure.error;
+  }
+  return status;
+}
+
+function launchFailure(error) {
+  if (error?.code === 'ENOENT') return { success: false, code: 'ENOENT', exitCode: 127, error: 'Child program was not found. Check its installation and PATH.' };
+  if (error?.code === 'EACCES') return { success: false, code: 'EACCES', exitCode: 126, error: 'Child program is not executable.' };
+  return { success: false, code: 'CHILD_LAUNCH_FAILED', exitCode: 1, error: 'Unable to launch the child program.' };
+}
+
+function launch(context, program, args, root, options) {
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = context.runChild(program, args, { cwd: root, stdio: 'inherit', shell: false });
+    } catch (error) { resolve(launchFailure(error)); return; }
+    const signals = options.signalSource || process;
+    const forwardInt = () => child.kill('SIGINT');
+    const forwardTerm = () => child.kill('SIGTERM');
+    signals.on('SIGINT', forwardInt);
+    signals.on('SIGTERM', forwardTerm);
+    const finish = result => {
+      signals.removeListener('SIGINT', forwardInt);
+      signals.removeListener('SIGTERM', forwardTerm);
+      resolve(result);
+    };
+    child.once('error', error => finish(launchFailure(error)));
+    child.once('close', (code, signal) => {
+      const exitCode = Number.isInteger(code) ? code : 128 + (constants.signals[signal] || 1);
+      finish({ success: exitCode === 0, exitCode, signal, ...(exitCode ? { error: `Child program exited with status ${exitCode}.` } : {}) });
+    });
+  });
+}
+
+function githubStatusResult(projectRoot, flags, args, options) {
+  const status = accountStatus(projectRoot, options);
+  const json = flags.json || flags['--json'] || args.includes('--json');
+  return { success: ['ready', 'unbound'].includes(status.state), status,
+    output: json ? JSON.stringify(status, null, 2) : renderStatus(status),
+    ...(status.error ? { error: status.error } : {}) };
+}
+
+async function handler(args = [], flags = {}, projectRoot = process.cwd(), options = {}) {
+  const delimiter = args.indexOf('--');
+  const ownArgs = stripGlobalFlags(delimiter < 0 ? args : args.slice(0, delimiter));
+  const verb = ownArgs[0];
+  if (!verb || verb === 'help' || (delimiter < 0 && (args.includes('--help') || args.includes('-h')))) {
+    return { success: true, output: usage };
+  }
+  try {
+    if (verb === 'use' && ownArgs.length === 2 && delimiter < 0) {
+      const context = prepareGithubAccount(projectRoot, ownArgs[1], options);
+      repositoryAccess(context, projectRoot, options);
+      writeGithubAccount(projectRoot, ownArgs[1], options);
+      return { success: true, account: context.account, output: `This clone uses GitHub account ${context.account}.` };
+    }
+    if (verb === 'status' && ownArgs.slice(1).every(arg => arg === '--json') && delimiter < 0) {
+      return githubStatusResult(projectRoot, flags, args, options);
+    }
+    if (verb === 'unset' && ownArgs.length === 1 && delimiter < 0) {
+      unsetGithubAccount(projectRoot, options);
+      return { success: true, output: 'Clone GitHub account binding removed; native account selection applies.' };
+    }
+    if (verb === 'run' && ownArgs.length === 1 && delimiter >= 0 && args[delimiter + 1]) {
+      const context = createGithubContext(projectRoot, { ...options, childRunner: options.childRunner || spawn });
+      return await launch(context, args[delimiter + 1], args.slice(delimiter + 2), projectRoot, options);
+    }
+    return { success: false, error: `Usage: ${usage}` };
+  } catch (error) { return safeFailure(error); }
+}
+
+module.exports = {
+  name: 'github',
+  description: 'Optional clone-local GitHub account selection and isolated session launch',
+  usage,
+  handler,
+};

package/lib/commands/hooks.js

@@ -29,8 +29,8 @@ const {
 } = require('../hook-global-installer');
 const fs = require('node:fs');
 const path = require('node:path');
-const { sessionStartCapability, userPromptSubmitCapability, sessionEndCapability } = require('../hook-renderer');
-const { buildMemoryDigest, defaultFetchIssues, defaultFetchNotes } = require('../memory-digest');
+const { sessionStartCapability, userPromptSubmitCapability, sessionEndCapability, readAttentionCapability } = require('../hook-renderer');
+const { buildMemoryDigest, buildReadAttentionDigest, defaultFetchIssues, defaultFetchNotes } = require('../memory-digest');
 const { collectInbox, buildInboxNudge } = require('../inbox');
 const { collectDigest } = require('../pr-monitor/digest');
 const { loadDispatchText } = require('../using-forge');
@@ -172,6 +172,7 @@ function usage() {
     + '       forge hooks inbox-pickup --harness <claude> (machine-facing; emits UserPromptSubmit context)\n'
     + '       forge hooks shepherd-events --harness <claude> (machine-facing; emits UserPromptSubmit PR-monitor deltas)\n'
     + '       forge hooks memory-recall --harness <claude> (machine-facing; emits UserPromptSubmit query-relevant memory)\n'
+    + '       forge hooks read-attention --harness <claude> (machine-facing; emits path-matched PreToolUse:Read context)\n'
     + '       forge hooks capture --harness <claude> --trigger <precompact|stop> (machine-facing; captures a session summary on exit)';
 }
 
@@ -212,12 +213,23 @@ const CAPTURE_TAGS = ['type:session-summary', CAPTURE_AUTO_TAG];
  * @returns {string}
  */
 function buildCaptureNote(trigger, issues) {
-  const capped = issues.slice(0, CAPTURE_ISSUE_CAP);
-  const lines = capped.map(issue => {
+  const stableIssues = [...new Map(issues.map(issue => {
+    const id = String((issue && issue.id) || '');
     const title = String((issue && (issue.title || issue.id)) || 'untitled').replace(/\s+/g, ' ').trim();
+    return [`${id}\0${title}`, { id, title }];
+  })).values()].sort((left, right) => {
+    const leftKey = `${left.id}\0${left.title}`;
+    const rightKey = `${right.id}\0${right.title}`;
+    if (leftKey < rightKey) return -1;
+    if (leftKey > rightKey) return 1;
+    return 0;
+  });
+  const capped = stableIssues.slice(0, CAPTURE_ISSUE_CAP);
+  const lines = capped.map(issue => {
+    const title = issue.title;
     return `- ${title.length > CAPTURE_TITLE_CAP ? `${title.slice(0, CAPTURE_TITLE_CAP)}…` : title}`;
   });
-  const more = issues.length > capped.length ? `\n- …and ${issues.length - capped.length} more` : '';
+  const more = stableIssues.length > capped.length ? `\n- …and ${stableIssues.length - capped.length} more` : '';
   const body = lines.length
     ? `Session boundary (${trigger}) — in-progress:\n${lines.join('\n')}${more}`
     : `Session boundary (${trigger}) — no in-progress issues.`;
@@ -299,6 +311,41 @@ function formatUserPromptSubmit(harness, text) {
   return '';
 }
 
+function formatPreToolUse(harness, text) {
+  if (harness !== 'claude') return '';
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text },
+  });
+}
+
+function fetchReadAttentionNotes(projectRoot) {
+  return projectMemory.recent(projectRoot, 100).map(entry => ({
+    note: typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value),
+    tags: Array.isArray(entry.tags) ? entry.tags : [],
+    sourceAgent: entry.sourceAgent,
+    timestamp: entry.timestamp,
+  }));
+}
+
+async function handleReadAttention(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    const capability = readAttentionCapability(harness);
+    if (!capability.rendered) return { success: true, output: '', reason: capability.reason };
+    const readInput = opts.readInput || readHookStdin;
+    const payload = JSON.parse(readInput() || '{}');
+    const targetPath = payload?.tool_input?.file_path || payload?.tool_input?.path;
+    if (!targetPath) return { success: true, output: '' };
+    const fetchNotes = opts.fetchNotes || fetchReadAttentionNotes;
+    const notes = await fetchNotes(projectRoot, { ...opts, noteLimit: 100 });
+    const digest = buildReadAttentionDigest(targetPath, notes, opts);
+    if (digest.empty) return { success: true, output: '' };
+    return { success: true, output: formatPreToolUse(harness, digest.text) };
+  } catch {
+    return { success: true, output: '' };
+  }
+}
+
 /**
  * `forge hooks inbox-pickup --harness <h>` — the COMPLIANT comment-back CONTEXT hook. On each
  * prompt it emits harness-native UserPromptSubmit JSON carrying a COMPACT count+pointer nudge
@@ -700,11 +747,12 @@ async function handler(args, flags = {}, projectRoot, opts = {}) {
   if (action === 'inbox-pickup') return handleInboxPickup(args.slice(1), projectRoot, opts);
   if (action === 'shepherd-events') return handleShepherdEvents(args.slice(1), projectRoot, opts);
   if (action === 'memory-recall') return handleMemoryRecall(args.slice(1), projectRoot, opts);
+  if (action === 'read-attention') return handleReadAttention(args.slice(1), projectRoot, opts);
   if (action === 'capture') return handleCapture(args.slice(1), projectRoot, opts);
   if (action === 'install') return handleInstall(args, flags, opts);
   return {
     success: false,
-    error: `forge hooks supports: install, session-start, inbox-pickup, shepherd-events, capture.\n${usage()}`,
+    error: `forge hooks supports: install, session-start, inbox-pickup, shepherd-events, memory-recall, read-attention, capture.\n${usage()}`,
   };
 }