@moretea-labs/forge 1.5.0-rc.1

package/src/cli/repositories/git-command-executor.ts

@@ -0,0 +1,301 @@
+import { createHash } from 'crypto';
+import { spawnSync } from 'child_process';
+import { appendFileSync, mkdirSync, realpathSync } from 'fs';
+import { dirname, join, relative } from 'path';
+import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
+import { repositoryControllerRoot } from './controller-home';
+import { classifyRepositoryCommand, type RepositoryCommandAuthorization, type RepositoryCommandClassification } from './command-classifier';
+import { resolveRepositoryCommandCwd } from './command-scope';
+import type { RepositoryRecord } from './types';
+import { assertResolvedAuthorization, decideAuthorization, type AuthorizationDecision } from '../../runtime/control-plane/governance/authorization';
+import { readRepositoryAccessPolicy } from '../../runtime/control-plane/governance/access-policy';
+
+export interface ExecuteRepositoryGitCommandInput {
+  args: string[];
+  cwd?: string;
+  authorization?: RepositoryCommandAuthorization;
+  approvalToken?: string;
+  dryRun?: boolean;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  authorizationDecision?: AuthorizationDecision;
+  approvalRequestId?: string;
+  sessionId?: string;
+  principalId?: string;
+  workId?: string;
+  goalId?: string;
+}
+
+export interface RepositoryGitSnapshot {
+  head: string | null;
+  branch: string | null;
+  status: string;
+  dirty: boolean;
+  refsHash: string;
+}
+
+export interface RepositoryGitExecution {
+  status: 'preview' | 'approval_required' | 'executed';
+  repoId: string;
+  checkoutId: string;
+  cwd: string;
+  command: string;
+  args: string[];
+  classification: RepositoryCommandClassification;
+  approvalToken: string;
+  authorization?: RepositoryCommandAuthorization;
+  authorizationDecision?: AuthorizationDecision;
+  approvalRequestId?: string;
+  ok?: boolean;
+  exitCode?: number;
+  timedOut?: boolean;
+  stdout?: string;
+  stderr?: string;
+  before: RepositoryGitSnapshot;
+  after?: RepositoryGitSnapshot;
+  repositoryChanged?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 15 * 60_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 128 * 1024;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const MAX_ARGS = 256;
+const MAX_ARG_LENGTH = 8192;
+
+function boundedInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value)) throw new Error('GIT_COMMAND_OPTION_INVALID: numeric option must be finite');
+  const normalized = Math.trunc(value);
+  if (normalized < minimum || normalized > maximum) {
+    throw new Error(`GIT_COMMAND_OPTION_INVALID: value must be between ${minimum} and ${maximum}`);
+  }
+  return normalized;
+}
+
+function gitEnvironment(): NodeJS.ProcessEnv {
+  const allowed = [
+    'PATH', 'HOME', 'USER', 'LOGNAME', 'TMPDIR', 'TMP', 'TEMP', 'SHELL',
+    'LANG', 'LC_ALL', 'TERM', 'SSH_AUTH_SOCK', 'GPG_TTY', 'XDG_CONFIG_HOME',
+  ];
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of allowed) if (process.env[key] !== undefined) env[key] = process.env[key];
+  env.GIT_TERMINAL_PROMPT = '0';
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.CI = '1';
+  return env;
+}
+
+function quoteArg(value: string): string {
+  return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function validateArgs(args: string[]): string[] {
+  if (!Array.isArray(args) || args.length === 0) throw new Error('GIT_COMMAND_INVALID: args are required');
+  if (args.length > MAX_ARGS) throw new Error(`GIT_COMMAND_INVALID: args exceed ${MAX_ARGS} entries`);
+  const normalized = args.map((entry) => String(entry));
+  for (const value of normalized) {
+    if (!value || value.length > MAX_ARG_LENGTH || value.includes('\0') || /[\r\n]/.test(value)) {
+      throw new Error('GIT_COMMAND_INVALID: args must be non-empty single-line strings within the size limit');
+    }
+  }
+  const lower = normalized.map((value) => value.toLowerCase());
+  // Git reuses `-c` both as a global config override (`git -c key=value status`)
+  // and as a normal subcommand option (`git switch -c feature/name`). Only the
+  // leading global-option form is forbidden. Short options are case-sensitive:
+  // `-C` changes the working directory while `-c` injects configuration.
+  for (let index = 0; index < normalized.length; index += 1) {
+    const raw = normalized[index]!;
+    const value = lower[index]!;
+    if (raw === '--') break;
+    if (!raw.startsWith('-')) break;
+    if (raw === '-c' || raw.startsWith('-c=') || value === '--config-env' || value.startsWith('--config-env=')) {
+      throw new Error('GIT_COMMAND_POLICY_DENIED: per-command Git configuration overrides are not allowed');
+    }
+    if (
+      raw === '-C'
+      || raw.startsWith('-C=')
+      || value === '--git-dir'
+      || value.startsWith('--git-dir=')
+      || value === '--work-tree'
+      || value.startsWith('--work-tree=')
+    ) {
+      throw new Error('GIT_COMMAND_SCOPE_DENIED: Git repository scope overrides are not allowed');
+    }
+    if (value === '--exec-path' || value.startsWith('--exec-path=')) {
+      throw new Error('GIT_COMMAND_POLICY_DENIED: Git executable-path overrides are not allowed');
+    }
+  }
+  if (lower.some((value) => value === '--git-dir' || value.startsWith('--git-dir=') || value === '--work-tree' || value.startsWith('--work-tree='))) {
+    throw new Error('GIT_COMMAND_SCOPE_DENIED: Git repository scope overrides are not allowed');
+  }
+  if (lower[0] === 'config' && lower.some((value) => value === '--global' || value === '--system')) {
+    throw new Error('GIT_COMMAND_POLICY_DENIED: global and system Git configuration are not allowed');
+  }
+  if (lower[0] === 'credential' || lower[0].startsWith('credential-')) {
+    throw new Error('GIT_COMMAND_POLICY_DENIED: credential helper access is not allowed');
+  }
+  if (lower[0] === 'upload-archive' || lower[0] === 'upload-pack' || lower[0] === 'receive-pack' || lower[0] === 'daemon') {
+    throw new Error('GIT_COMMAND_POLICY_DENIED: Git transport server commands are not allowed');
+  }
+  return normalized;
+}
+
+function runGit(root: string, args: string[], timeoutMs: number, maxOutputBytes: number) {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    cwd: root,
+    env: gitEnvironment(),
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+    maxBuffer: Math.max(maxOutputBytes, 1024 * 1024),
+  });
+  const error = result.error instanceof Error ? result.error.message : '';
+  return {
+    ok: result.status === 0 && !result.error,
+    exitCode: result.status ?? 1,
+    timedOut: (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT',
+    stdout: capProcessOutput(redactProcessOutput(typeof result.stdout === 'string' ? result.stdout : ''), maxOutputBytes),
+    stderr: capProcessOutput(redactProcessOutput([
+      typeof result.stderr === 'string' ? result.stderr : '',
+      error,
+    ].filter(Boolean).join('\n')), maxOutputBytes),
+  };
+}
+
+function gitText(root: string, args: string[]): string {
+  const result = runGit(root, args, 10_000, 256 * 1024);
+  return result.ok ? result.stdout.trim() : '';
+}
+
+function repositorySnapshot(root: string): RepositoryGitSnapshot {
+  const head = gitText(root, ['rev-parse', '--verify', 'HEAD']) || null;
+  const branch = gitText(root, ['branch', '--show-current']) || null;
+  const status = gitText(root, ['status', '--porcelain=v1', '--branch', '--', '.', ':(exclude).ai/harness/**']);
+  const refs = gitText(root, ['show-ref', '--heads', '--tags']);
+  return {
+    head,
+    branch,
+    status,
+    dirty: status.split(/\r?\n/).some((line) => line.trim() && !line.startsWith('##')),
+    refsHash: createHash('sha256').update(refs).digest('hex'),
+  };
+}
+
+function approvalToken(
+  repository: RepositoryRecord,
+  relativeCwd: string,
+  args: string[],
+  classification: RepositoryCommandClassification,
+  snapshot: RepositoryGitSnapshot,
+): string {
+  return createHash('sha256').update(JSON.stringify({
+    version: 1,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    cwd: relativeCwd,
+    args,
+    classification,
+    snapshot,
+  })).digest('hex');
+}
+
+function snapshotChanged(before: RepositoryGitSnapshot, after: RepositoryGitSnapshot): boolean {
+  return before.head !== after.head
+    || before.branch !== after.branch
+    || before.status !== after.status
+    || before.refsHash !== after.refsHash;
+}
+
+function auditExecution(controllerHome: string, repository: RepositoryRecord, execution: RepositoryGitExecution): void {
+  const path = join(repositoryControllerRoot(controllerHome, repository.repoId), 'audit', 'git-commands.jsonl');
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify({
+    timestamp: new Date().toISOString(),
+    ...execution,
+    stdout: execution.stdout ? `[${Buffer.byteLength(execution.stdout, 'utf8')} bytes returned]` : undefined,
+    stderr: execution.stderr ? `[${Buffer.byteLength(execution.stderr, 'utf8')} bytes returned]` : undefined,
+  })}\n`, 'utf-8');
+}
+
+export function executeRepositoryGitCommand(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  input: ExecuteRepositoryGitCommandInput,
+): RepositoryGitExecution {
+  const { root, cwd, relativeCwd } = resolveRepositoryCommandCwd(repository, input.cwd);
+  if (realpathSync(root) !== realpathSync(repository.canonicalRoot)) {
+    throw new Error('GIT_COMMAND_SCOPE_DENIED: selected checkout does not match the registered repository');
+  }
+  const args = validateArgs(input.args);
+  const command = `git ${args.map(quoteArg).join(' ')}`;
+  const classification = classifyRepositoryCommand(command, repository.defaultBranch);
+  const before = repositorySnapshot(root);
+  const token = approvalToken(repository, relativeCwd, args, classification, before);
+  const permission = readRepositoryAccessPolicy(controllerHome, repository.repoId);
+  const safeMergedBranchDelete = classification.risk === 'destructive'
+    && /^git\s+branch\s+-d(?:\s|$)/i.test(command);
+  const risk = classification.risk === 'readonly'
+    ? 'readonly'
+    : classification.risk === 'remote_write'
+      ? 'remote_write'
+      : classification.risk === 'destructive' && !safeMergedBranchDelete ? 'destructive' : 'local_git';
+  const authorizationDecision = input.authorizationDecision ?? decideAuthorization({
+    controllerHome,
+    accessMode: permission.mode,
+    risk,
+    repositoryId: repository.repoId,
+    currentRepositoryId: repository.repoId,
+    permissionSnapshotVersion: permission.revision,
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    ...(input.principalId ? { principalId: input.principalId } : {}),
+    ...(input.workId ? { workId: input.workId, boundWorkId: input.workId } : {}),
+    ...(input.goalId ? { goalId: input.goalId, boundGoalId: input.goalId } : {}),
+    command,
+  });
+  const resolved = input.approvalRequestId
+    ? assertResolvedAuthorization({ controllerHome, repositoryId: repository.repoId, approvalRequestId: input.approvalRequestId, sessionId: input.sessionId, principalId: input.principalId, workId: input.workId, permissionSnapshotVersion: permission.revision, command })
+    : undefined;
+  const effectiveDecision = resolved
+    ? { decision: 'allow', source: 'user_confirmation', reason: 'Resolved approval request matches the exact Git operation and current permission snapshot.' } as const
+    : authorizationDecision;
+  const base: RepositoryGitExecution = {
+    status: input.dryRun === true ? 'preview' : 'approval_required',
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    cwd: relative(root, cwd) || relativeCwd,
+    command: redactProcessOutput(command),
+    args: args.map((value) => redactProcessOutput(value)),
+    classification,
+    approvalToken: token,
+    authorization: input.authorization,
+    authorizationDecision: effectiveDecision,
+    ...(effectiveDecision.decision === 'user_confirmation_required' ? { approvalRequestId: effectiveDecision.approvalRequestId } : {}),
+    before,
+  };
+  if (input.dryRun === true) {
+    auditExecution(controllerHome, repository, base);
+    return base;
+  }
+  const confirmed = input.authorization === 'confirmed_plan' && input.approvalToken === token;
+  const canExecute = classification.risk === 'readonly'
+    || effectiveDecision.decision === 'allow'
+    || confirmed;
+  if (!canExecute) {
+    auditExecution(controllerHome, repository, base);
+    return base;
+  }
+  const timeoutMs = boundedInteger(input.timeoutMs, DEFAULT_TIMEOUT_MS, 1_000, MAX_TIMEOUT_MS);
+  const maxOutputBytes = boundedInteger(input.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, 1_024, MAX_OUTPUT_BYTES);
+  const processResult = runGit(cwd, args, timeoutMs, maxOutputBytes);
+  const after = repositorySnapshot(root);
+  const execution: RepositoryGitExecution = {
+    ...base,
+    status: 'executed',
+    ...processResult,
+    after,
+    repositoryChanged: snapshotChanged(before, after),
+  };
+  auditExecution(controllerHome, repository, execution);
+  return execution;
+}

package/src/cli/repositories/goal-registry.ts

@@ -0,0 +1,239 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { listControllerChecks, runControllerCheck, type ControllerCheckResult } from '../controller/check-runner';
+import { repositoryGitStatus } from './structured-git';
+import type { RepositoryRecord } from './types';
+
+export interface RepositoryGoal {
+  id: string;
+  title: string;
+  status: 'active' | 'paused' | 'done';
+  checks: string[];
+  notes?: string;
+  updatedAt: string;
+  createdAt: string;
+  lastRunId?: string;
+  lastRunStatus?: RepositoryGoalRun['status'];
+}
+
+export interface RepositoryGoalRegistry {
+  schemaVersion: 1;
+  goals: RepositoryGoal[];
+}
+
+export interface RepositoryStuckTrace {
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  message: string;
+  next: string;
+  evidence?: Record<string, unknown>;
+}
+
+export interface RepositoryStuckDiagnosis {
+  repoId: string;
+  checkoutId: string;
+  generatedAt: string;
+  git: ReturnType<typeof repositoryGitStatus>;
+  activeGoals: RepositoryGoal[];
+  likelyBlocked: boolean;
+  blockers: RepositoryStuckTrace[];
+}
+
+export interface RepositoryGoalRun {
+  schemaVersion: 1;
+  runId: string;
+  repoId: string;
+  checkoutId: string;
+  goalId: string;
+  title: string;
+  status: 'succeeded' | 'failed' | 'blocked' | 'skipped';
+  startedAt: string;
+  finishedAt: string;
+  gitBefore: ReturnType<typeof repositoryGitStatus>;
+  gitAfter: ReturnType<typeof repositoryGitStatus>;
+  checks: Array<{
+    checkId: string;
+    status: 'passed' | 'failed' | 'missing' | 'skipped';
+    summary: string;
+    artifactPath?: string;
+  }>;
+  diagnosis: RepositoryStuckDiagnosis;
+  next: string[];
+}
+
+export interface RepositoryGoalRunResult {
+  run: RepositoryGoalRun;
+  path: string;
+  registry: RepositoryGoalRegistry;
+}
+
+const REGISTRY_PATH = '.forge/goals.json';
+const RUNS_ROOT = '.forge/goal-runs';
+const MAX_RUNS = 100;
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function registryPath(repository: RepositoryRecord): string {
+  return join(repository.canonicalRoot, REGISTRY_PATH);
+}
+
+function runsRoot(repository: RepositoryRecord): string {
+  return join(repository.canonicalRoot, RUNS_ROOT);
+}
+
+function runPath(repository: RepositoryRecord, runId: string): string {
+  return join(runsRoot(repository), `${runId}.json`);
+}
+
+function slug(value: string): string {
+  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || `goal-${Date.now()}`;
+}
+
+function writeJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+export function readRepositoryGoalRegistry(repository: RepositoryRecord): RepositoryGoalRegistry {
+  const absolute = registryPath(repository);
+  if (!existsSync(absolute)) return { schemaVersion: 1, goals: [] };
+  const parsed = JSON.parse(readFileSync(absolute, 'utf-8')) as Partial<RepositoryGoalRegistry>;
+  return { schemaVersion: 1, goals: Array.isArray(parsed.goals) ? parsed.goals : [] };
+}
+
+function writeRepositoryGoalRegistry(repository: RepositoryRecord, registry: RepositoryGoalRegistry): void {
+  writeJson(registryPath(repository), registry);
+}
+
+export function upsertRepositoryGoal(repository: RepositoryRecord, input: { id?: unknown; title?: unknown; status?: unknown; checks?: unknown; notes?: unknown }): { path: string; goal: RepositoryGoal; registry: RepositoryGoalRegistry } {
+  const registry = readRepositoryGoalRegistry(repository);
+  const title = String(input.title ?? '').trim();
+  const id = String(input.id ?? '').trim() || slug(title);
+  if (!id) throw new Error('REPOSITORY_GOAL_ID_REQUIRED: id or title is required');
+  const statusValue = String(input.status ?? 'active');
+  const status = (['active', 'paused', 'done'].includes(statusValue) ? statusValue : 'active') as RepositoryGoal['status'];
+  const checks = Array.isArray(input.checks) ? input.checks.map((item) => String(item).trim()).filter(Boolean) : [];
+  const existing = registry.goals.find((goal) => goal.id === id);
+  const at = now();
+  const goal: RepositoryGoal = {
+    id,
+    title: title || existing?.title || id,
+    status,
+    checks: checks.length > 0 ? checks : existing?.checks ?? [],
+    notes: typeof input.notes === 'string' ? input.notes : existing?.notes,
+    createdAt: existing?.createdAt ?? at,
+    updatedAt: at,
+    lastRunId: existing?.lastRunId,
+    lastRunStatus: existing?.lastRunStatus,
+  };
+  registry.goals = [goal, ...registry.goals.filter((entry) => entry.id !== id)].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+  writeRepositoryGoalRegistry(repository, registry);
+  return { path: REGISTRY_PATH, goal, registry };
+}
+
+function availableCheckIds(repository: RepositoryRecord): Set<string> {
+  try { return new Set(listControllerChecks(repository.canonicalRoot).map((check) => check.id)); }
+  catch (_error) { return new Set(); }
+}
+
+export function diagnoseRepositoryStuckState(repository: RepositoryRecord): RepositoryStuckDiagnosis {
+  const generatedAt = now();
+  const git = repositoryGitStatus(repository);
+  const activeGoals = readRepositoryGoalRegistry(repository).goals.filter((goal) => goal.status === 'active');
+  const blockers: RepositoryStuckDiagnosis['blockers'] = [];
+  const dirtyLines = git.porcelain.split(/\r?\n/).filter((line) => line && !line.startsWith('## '));
+  if (dirtyLines.length > 0) blockers.push({ code: 'DIRTY_WORKTREE', severity: 'warning', message: `${dirtyLines.length} dirty Git path(s) are present.`, next: 'Run repository_git_diff, then repository_git_commit or revert selected paths.', evidence: { staged: git.staged, unstaged: git.unstaged, untracked: git.untracked } });
+  if (activeGoals.length === 0) blockers.push({ code: 'NO_ACTIVE_GOAL', severity: 'info', message: 'No active repository goal is registered.', next: 'Create one with repository_goal_upsert so agent work has a durable target.' });
+  if (!git.branch) blockers.push({ code: 'DETACHED_HEAD', severity: 'error', message: 'Checkout is not on a named branch.', next: 'Use repository_git_create_branch or repository_git_switch_branch before continuing edits.' });
+  const checks = availableCheckIds(repository);
+  for (const goal of activeGoals) {
+    const missing = goal.checks.filter((check) => !checks.has(check));
+    if (missing.length > 0) blockers.push({ code: 'MISSING_GOAL_CHECKS', severity: 'warning', message: `Goal ${goal.id} references missing check(s): ${missing.join(', ')}`, next: 'Update the goal checks or add them to .forge/checks.json/package scripts.', evidence: { goalId: goal.id, missing } });
+  }
+  return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, generatedAt, git, activeGoals, likelyBlocked: blockers.some((blocker) => blocker.severity !== 'info'), blockers };
+}
+
+function selectedGoal(repository: RepositoryRecord, goalId: unknown): RepositoryGoal | undefined {
+  const goals = readRepositoryGoalRegistry(repository).goals;
+  const requested = typeof goalId === 'string' ? goalId.trim() : '';
+  if (requested) return goals.find((goal) => goal.id === requested);
+  return goals.find((goal) => goal.status === 'active');
+}
+
+function checkSummary(result: ControllerCheckResult): string {
+  return `${result.check.id}: ${result.ok ? 'passed' : 'failed'} (${result.status}${result.timedOut ? ', timed out' : ''})`;
+}
+
+function pruneRuns(repository: RepositoryRecord): void {
+  const root = runsRoot(repository);
+  if (!existsSync(root)) return;
+  const files = readdirSync(root).filter((name) => name.endsWith('.json')).sort().reverse();
+  for (const file of files.slice(MAX_RUNS)) {
+    try { writeFileSync(join(root, file), readFileSync(join(root, file))); }
+    catch (_error) { /* best effort no-op; avoid destructive cleanup here */ }
+  }
+}
+
+export function runRepositoryGoal(repository: RepositoryRecord, input: { goalId?: unknown; runChecks?: unknown } = {}): RepositoryGoalRunResult {
+  const goal = selectedGoal(repository, input.goalId);
+  if (!goal) throw new Error('REPOSITORY_GOAL_NOT_FOUND: no active or requested goal exists');
+  if (goal.status !== 'active') throw new Error(`REPOSITORY_GOAL_NOT_ACTIVE: ${goal.id} is ${goal.status}`);
+  const startedAt = now();
+  const runId = `GOAL-${Date.now()}-${goal.id.replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 48)}`;
+  const gitBefore = repositoryGitStatus(repository);
+  const diagnosis = diagnoseRepositoryStuckState(repository);
+  const checks: RepositoryGoalRun['checks'] = [];
+  const knownChecks = availableCheckIds(repository);
+  if (goal.checks.length === 0) {
+    checks.push({ checkId: '(none)', status: 'skipped', summary: 'Goal has no checks configured.' });
+  } else if (input.runChecks !== true) {
+    checks.push(...goal.checks.map((checkId) => ({ checkId, status: 'skipped' as const, summary: 'Checks were not executed; pass run_checks=true to run them.' })));
+  } else {
+    for (const checkId of goal.checks) {
+      if (!knownChecks.has(checkId)) {
+        checks.push({ checkId, status: 'missing', summary: `Check not found: ${checkId}` });
+        continue;
+      }
+      try {
+        const check = runControllerCheck(repository.canonicalRoot, checkId);
+        checks.push({ checkId, status: check.ok ? 'passed' : 'failed', summary: checkSummary(check), artifactPath: check.artifactPath });
+      } catch (error) {
+        checks.push({ checkId, status: 'failed', summary: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  const gitAfter = repositoryGitStatus(repository);
+  const hardBlockers = diagnosis.blockers.filter((blocker) => blocker.severity === 'error');
+  const failedChecks = checks.filter((check) => check.status === 'failed' || check.status === 'missing');
+  const status: RepositoryGoalRun['status'] = hardBlockers.length > 0 ? 'blocked' : failedChecks.length > 0 ? 'failed' : 'succeeded';
+  const finishedAt = now();
+  const next = [
+    ...diagnosis.blockers.map((blocker) => blocker.next),
+    ...(failedChecks.length > 0 ? ['Inspect failed check artifacts, patch the failures, and re-run repository_goal_run.'] : []),
+    ...(gitAfter.clean ? ['No dirty worktree changes remain after this goal run.'] : ['Review repository_git_diff and commit or revert current changes.']),
+  ];
+  const run: RepositoryGoalRun = { schemaVersion: 1, runId, repoId: repository.repoId, checkoutId: repository.activeCheckoutId, goalId: goal.id, title: goal.title, status, startedAt, finishedAt, gitBefore, gitAfter, checks, diagnosis, next: [...new Set(next)] };
+  writeJson(runPath(repository, runId), run);
+  const registry = readRepositoryGoalRegistry(repository);
+  registry.goals = registry.goals.map((entry) => entry.id === goal.id ? { ...entry, lastRunId: runId, lastRunStatus: status, updatedAt: finishedAt } : entry);
+  writeRepositoryGoalRegistry(repository, registry);
+  pruneRuns(repository);
+  return { run, path: `${RUNS_ROOT}/${runId}.json`, registry };
+}
+
+export function listRepositoryGoalRuns(repository: RepositoryRecord, limit = 20): RepositoryGoalRun[] {
+  const root = runsRoot(repository);
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, Math.max(1, Math.min(Math.trunc(limit), MAX_RUNS)))
+    .flatMap((name) => {
+      try { return [JSON.parse(readFileSync(join(root, name), 'utf-8')) as RepositoryGoalRun]; }
+      catch (_error) { return []; }
+    });
+}

package/src/cli/repositories/identity.ts

@@ -0,0 +1,64 @@
+import { createHash, randomUUID } from 'crypto';
+import { basename } from 'path';
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function normalizeRemoteUrl(input: string | undefined): string | undefined {
+  const raw = input?.trim();
+  if (!raw) return undefined;
+
+  const scpLike = /^(?:([^@\s]+)@)?([^:/\s]+):(.+)$/.exec(raw);
+  const expanded = scpLike && !raw.includes('://')
+    ? `ssh://${scpLike[1] ? `${scpLike[1]}@` : ''}${scpLike[2]}/${scpLike[3]}`
+    : raw;
+
+  try {
+    const url = new URL(expanded);
+    const host = url.hostname.toLowerCase();
+    const port = url.port ? `:${url.port}` : '';
+    const path = decodeURIComponent(url.pathname)
+      .replace(/\\/g, '/')
+      .replace(/\/+$/, '')
+      .replace(/\.git$/i, '')
+      .replace(/^\/+/, '')
+      .toLowerCase();
+    if (!host || !path) return undefined;
+    return `${host}${port}/${path}`;
+  } catch (_error) {
+    return raw
+      .replace(/\\/g, '/')
+      .replace(/\/+$/, '')
+      .replace(/\.git$/i, '')
+      .toLowerCase();
+  }
+}
+
+export function stableRemoteRepoId(canonicalRemote: string): string {
+  return `repo_${digest(`remote\0${canonicalRemote}`).slice(0, 24)}`;
+}
+
+export function newLocalRepoId(): string {
+  return `repo_local_${randomUUID().replace(/-/g, '')}`;
+}
+
+export function stableCheckoutId(repoId: string, canonicalRoot: string): string {
+  return `checkout_${digest(`${repoId}\0${canonicalRoot}`).slice(0, 24)}`;
+}
+
+export function stableWorktreeId(repoId: string, canonicalRoot: string): string {
+  return `worktree_${digest(`${repoId}\0${canonicalRoot}`).slice(0, 24)}`;
+}
+
+export function parseGitHubRemote(canonicalRemote: string | undefined): { owner: string; repo: string } | undefined {
+  if (!canonicalRemote) return undefined;
+  const match = /^github\.com\/([^/]+)\/([^/]+)$/i.exec(canonicalRemote);
+  if (!match) return undefined;
+  return { owner: match[1], repo: match[2] };
+}
+
+export function inferDisplayName(root: string, canonicalRemote?: string): string {
+  const remoteName = canonicalRemote?.split('/').at(-1)?.trim();
+  return remoteName || basename(root) || 'repository';
+}