holo-codex 0.1.0

package/docs/release-checklist.md

@@ -0,0 +1,144 @@
+# HOLO-Codex npm Release Checklist
+
+Use this checklist for npm releases such as `v0.1.0`.
+
+The public source release remains available at `https://github.com/tizerluo/HOLO-Codex`. The npm package is `holo-codex` and installs the stable `agent-loop` CLI. Compatibility identifiers remain unchanged: `agent-loop`, `.agent-loop/`, `autonomous-pr-loop`, and `plugins/autonomous-pr-loop/`.
+
+## Pre-Publish Validation
+
+Run from the release checkout:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build:hooks
+pnpm lint
+pnpm test
+npm pack --ignore-scripts --dry-run --json
+npm view holo-codex name version dist-tags --json || true
+```
+
+Before the first publish, `npm view holo-codex ...` should return `E404`. For later releases, confirm the registry version is lower than the version in `package.json`.
+
+Review the pack output for accidental private material. The package must include the CLI, hooks dist, dashboard UI source, schemas, plugin metadata, MCP server, skills, public docs, and brand assets. It must not include tests, private planning/spec/research docs, `.agent-loop/`, raw logs, raw hook payloads, raw transcripts, or local backups.
+
+Run a secret and local-state scan:
+
+```bash
+rg -n "(ghp_|gho_|github_pat_|sk-[A-Za-z0-9]|dashboard token|AGENT_LOOP_MCP_TOKEN)" .
+find . -path './.git' -prune -o -path './node_modules' -prune -o -name '.agent-loop' -print
+```
+
+Expected result: no real tokens, no committed `.agent-loop/`, no raw hook payloads, no raw transcripts, no private handoff, and no historical `docs/plans/`, `docs/specs/`, or `docs/research/` material.
+
+## Tarball Smoke
+
+```bash
+npm pack --ignore-scripts --json
+tmp="$(mktemp -d)"
+export CODEX_HOME="$tmp/codex-home"
+mkdir -p "$tmp/target-repo"
+git -C "$tmp/target-repo" init -b main
+git -C "$tmp/target-repo" remote add origin https://github.com/example/holo-codex-smoke.git
+npm install --prefix "$tmp/install" ./holo-codex-*.tgz
+"$tmp/install/node_modules/.bin/agent-loop" --help
+"$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" init --json
+"$tmp/install/node_modules/.bin/agent-loop" install-hooks --repo "$tmp/target-repo" --json
+"$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" local doctor --json
+```
+
+Do not publish if this smoke fails.
+
+## Publish
+
+Confirm npm authentication without printing tokens:
+
+```bash
+npm whoami
+npm ping --json
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+If npm requires 2FA, complete the interactive prompt locally. Do not paste npm tokens or one-time codes into docs, PR bodies, issue comments, commits, artifacts, or screenshots.
+
+## Post-Publish Smoke
+
+Install from the registry in a fresh temporary prefix:
+
+```bash
+tmp="$(mktemp -d)"
+export CODEX_HOME="$tmp/codex-home"
+mkdir -p "$tmp/target-repo"
+git -C "$tmp/target-repo" init -b main
+git -C "$tmp/target-repo" remote add origin https://github.com/example/holo-codex-smoke.git
+npm install --prefix "$tmp/install" holo-codex
+"$tmp/install/node_modules/.bin/agent-loop" --help
+"$tmp/install/node_modules/.bin/agent-loop" local doctor --help
+"$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" init --json
+"$tmp/install/node_modules/.bin/agent-loop" install-hooks --repo "$tmp/target-repo" --json
+test -f "$tmp/install/node_modules/holo-codex/plugins/autonomous-pr-loop/.codex-plugin/plugin.json"
+```
+
+Optional dashboard smoke:
+
+```bash
+"$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" dashboard
+```
+
+Open the printed loopback URL and confirm Mission Control loads without a token in the URL. Do not copy the fallback token into release notes, screenshots, logs, or PR comments.
+
+## Source Install Smoke
+
+Keep the source path working as a fallback and development path:
+
+```bash
+git clone https://github.com/tizerluo/HOLO-Codex.git /tmp/holo-codex-release-smoke
+cd /tmp/holo-codex-release-smoke
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm test
+pnpm build:hooks
+pnpm agent-loop local install --repo /path/to/sandbox-repo
+agent-loop local doctor --repo /path/to/sandbox-repo
+agent-loop --repo /path/to/sandbox-repo doctor
+```
+
+## Rollback Smoke
+
+Use a fake or disposable `CODEX_HOME` unless a real rollback is explicitly intended:
+
+```bash
+export CODEX_HOME=/tmp/holo-codex-release-codex-home
+agent-loop local install --repo /path/to/sandbox-repo
+agent-loop local snapshots
+agent-loop local rollback --snapshot /path/to/snapshot
+agent-loop local doctor --repo /path/to/sandbox-repo
+```
+
+Expected result: hooks and binding registry restore from the snapshot, non-agent-loop hooks remain untouched, and malformed current hook files are preserved with a `.broken-<timestamp>` suffix when present.
+
+## GitHub Release
+
+After publish and post-publish smoke pass:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 \
+  --repo tizerluo/HOLO-Codex \
+  --title "HOLO-Codex v0.1.0" \
+  --notes-file /path/to/release-notes.md
+```
+
+Release notes must state:
+
+- HOLO-Codex is an observable workflow loop control plane for long-running Codex work; PR delivery is the first bundled workflow.
+- npm install path: `npm install --global holo-codex`.
+- Source install path: `git clone https://github.com/tizerluo/HOLO-Codex.git`.
+- Rollback uses `agent-loop local rollback --snapshot <snapshot>`.
+- npm uninstall removes the package, but shared HOLO-Codex router entries in `~/.codex/hooks.json` must be removed manually only after all target repo bindings are gone.
+- Runtime state, tokens, raw hook payloads, raw transcripts, and dashboard tokens must not be committed or shared.

package/docs/self-bootstrap.md

@@ -0,0 +1,150 @@
+# HOLO-Codex Self-Bootstrapping Workflow
+
+这份 runbook 说明 HOLO-Codex 如何使用自己的 `agent-loop` 交付流程维护自己。
+
+默认下一项工作来源是 **GitHub issues**。历史 plans/specs/research 不属于公开源码树；只有 issue 明确要求新增公开设计文档时，才新增新的公开文档。
+
+## 启动一次自举维护
+
+先从干净且最新的 `main` 开始：
+
+```bash
+git status --short --branch
+git switch main
+git pull --ff-only origin main
+pnpm agent-loop status --json
+pnpm agent-loop observe --json
+gh issue list --repo tizerluo/HOLO-Codex --state open --limit 30
+```
+
+如果目标是审计一次 dashboard-first 或 agent-loop-first 交付，使用 [Agent-loop-first Delivery Audit Checklist](./checklists/agent-loop-first-delivery-audit.md) 记录检查动作、证据位置和 PASS/PARTIAL/GAP 结论。
+
+如果 status 是 `BLOCKED`，不要直接开新实现分支。先通过 `status`、`observe`、`timeline`、`workers` 检查 gate：
+
+```bash
+pnpm agent-loop timeline --limit 20 --json
+pnpm agent-loop workers --events --json
+```
+
+如果 active terminal worker gate 已经过时，可以显式 recovery，再决定是否 resume：
+
+```bash
+pnpm agent-loop recover --json
+pnpm agent-loop resume
+```
+
+如果 gate 仍然有效，应该 stop run，或带 note approve gate。不要只在聊天里绕过 active gate；每个决定都必须留下 CLI、dashboard、event 或 PR 记录。
+
+## 选择下一项工作
+
+选择顺序：
+
+1. 用户明确指定的 issue 优先。
+2. 否则从 open GitHub issues 中，结合当前 handoff 优先级选择。
+3. manual goal 只用于很小的人工 override；如果目标不小，先创建或选择 GitHub issue。
+4. 公开源码树不依赖历史 `docs/specs` 或 `docs/plans` 队列；需要设计背景时，以当前 issue 和公开 docs 为准。
+
+开工前读取 issue body、当前 handoff 和相关文档。保持一个 issue 一个 PR。相关且安全的小发现应尽量在当前 PR 修掉，不要制造不必要的 follow-up issue。
+
+真实 `$pr-delivery-loop` 工作应先绑定 dashboard-visible run：
+
+```bash
+pnpm agent-loop init
+pnpm agent-loop install-hooks --repo "$PWD" --json
+pnpm agent-loop delivery bind \
+  --issue ISSUE_NUMBER \
+  --title "Issue title" \
+  --url https://github.com/tizerluo/HOLO-Codex/issues/ISSUE_NUMBER \
+  --json
+```
+
+Fresh repo 必须先 `init`，否则 `delivery bind` 没有 `.agent-loop/config.json` 和本地 SQLite 状态可写。已有 `.agent-loop/` 的仓库可以跳过重复初始化。
+
+后续手工 commander 动作、review report、CI/merge readiness 和 cleanup 应记录到同一个 run。阶段开始和完成优先使用 `pnpm agent-loop delivery stage ...`，让 Mission Control 在文件编辑前就能显示当前阶段：
+
+```bash
+pnpm agent-loop delivery stage \
+  --run RUN_ID \
+  --stage build \
+  --substage implementation_active \
+  --status active \
+  --summary "Implementation started after plan approval." \
+  --json
+```
+
+普通证据、review report、CI/merge readiness 和 cleanup 仍可用 `pnpm agent-loop evidence append ...`。PR body、PR owner comment、tester/reviewer/Claude/AGY report comment 都应包含 run id，方便 GitHub 和 dashboard 互相对照。
+
+Review/tester report 不只写自由文本 summary。派发、启动、完成、跳过或失败都应写结构化 review evidence：
+
+```bash
+pnpm agent-loop evidence append \
+  --run RUN_ID \
+  --stage review \
+  --substage claude_acp_review \
+  --reviewer claude_acp \
+  --requirement required \
+  --progress complete \
+  --result pass \
+  --severity none \
+  --comment-url "https://github.com/OWNER/REPO/pull/PR#issuecomment-ID" \
+  --summary "Claude ACP review completed with PASS." \
+  --json
+```
+
+`complete` review evidence 必须链接 PR issue comment；`block` 或 `p2_or_higher` 会让 merge readiness 保持阻塞，直到同 PR 修复或按规则路由。
+
+## 交付一个 PR
+
+每个 issue 使用这条 loop：
+
+```text
+read issue and handoff
+-> run GitNexus impact for code symbols to be edited
+-> write or update the development plan
+-> create branch from main
+-> implement
+-> run focused tests
+-> run independent tester/reviewer when useful or requested
+-> fix all real P0/P1/P2 findings
+-> run pnpm lint, pnpm test, and GitNexus detect
+-> commit, push, open PR
+-> wait for CI/review
+-> fix any CI/review blocker in the same PR
+-> merge
+-> switch main, pull, rebuild GitNexus index
+```
+
+合并后的固定收尾：
+
+```bash
+git switch main
+git pull --ff-only origin main
+npx gitnexus analyze
+git status --short --branch
+```
+
+## Review 和 follow-up 纪律
+
+- P0/P1 必须在当前 PR 修。
+- P2 如果相关且安全，应在当前 PR 修。
+- 只有当问题真实、超出当前 issue、且不能安全地在当前 PR 完成时，才创建 follow-up issue。
+- P3 polish 如果很小，通常直接在当前 PR 修；否则只记录，不制造 issue 噪音。
+- CI failure 永远不是当前 PR 的非阻塞 follow-up。
+
+## CLI 安全注意
+
+Mutating commands 包括 `recover`、`approve-gate`、`resume`、`stop`、`run`、`step`、`install-hooks`、`hooks install-router`、`hooks bind`、`hooks unbind`。`--help` 必须只打印 usage，不能修改 `.agent-loop` 状态或 hook registry。
+
+Dashboard URL 只绑定 loopback。token 是本地 session secret，不能写入 commit、PR body、docs、logs、artifacts 或截图。
+
+## 修改本 runbook 时的验证
+
+```bash
+pnpm test plugins/autonomous-pr-loop/tests/cli-run.test.ts
+pnpm lint
+pnpm test
+pnpm agent-loop status --json
+pnpm agent-loop observe --json
+```
+
+只有 PR 改 dashboard UI 或 live dashboard 行为时，才需要 Browser 验收。

package/docs/trust-and-safety.md

@@ -0,0 +1,45 @@
+# Trust And Safety
+
+English: Safety boundaries keep workers scoped, supervisor actions auditable, and secrets out of durable artifacts.
+
+中文：安全边界确保 worker 只做受控实现，supervisor 操作可审计，密钥不会进入持久化 artifacts。
+
+See also: [README](../README.md) / [中文 README](../README.zh-CN.md).
+
+## Worker Boundary
+
+Delegated workers may edit workspace files and return structured results. They must not commit, push, create PRs, mark PRs ready, or merge. The supervisor owns Git and GitHub lifecycle actions.
+
+Worker prompts, command policy, Codex sandboxing, and PR E hooks all reinforce this boundary.
+
+## Hooks Coverage
+
+Hooks cover the Codex tool loop only. `PreToolUse` blocks destructive Git/GitHub commands and lifecycle actions when state gates are not satisfied.
+
+Hooks do not intercept commands a user runs in an external Terminal.
+
+## MCP Mutations
+
+Mutating MCP tools require `AGENT_LOOP_MCP_TOKEN`. Calls without the matching token return `needs_secret_or_login` and do not update loop state.
+
+## Merge Safety
+
+`mergeMode` is the canonical merge policy. Legacy `allowAutoMerge` is accepted only as compatibility input. Merge still requires review, CI, open-comment, scope, and policy gates to pass.
+
+## Generic Loop Safety
+
+`generic-loop` uses the same supervisor, storage, gate, artifact, and audit boundaries as `pr-loop`. Planning and review states run read-only. Write-capable generic states require profile-scoped write roots and still pass through scope guard and hook policy.
+
+## Dashboard Tokens
+
+`agent-loop dashboard` prints the loopback URL on stdout and the session token on stderr. The dashboard login stores the token in browser localStorage and sends it as `x-agent-loop-token`. Mutation endpoints still require the token and loopback/origin guard. CLI `observe --json`, audit export, and normal dashboard URLs do not include the token.
+
+## Secrets And Logs
+
+Do not write secrets to code, docs, reports, logs, artifacts, commits, or PR bodies. Store local credentials in the operating system keychain or the user's configured secret manager.
+
+Command output may be stored as `.agent-loop/` artifacts. Review output before sharing it outside the local machine.
+
+## Runtime State
+
+`.agent-loop/`, SQLite state files, WAL/SHM files, raw worker JSONL, and hook logs are runtime data and must not be committed.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "holo-codex",
+  "version": "0.1.0",
+  "description": "Human On Loop Codex control plane for observable, recoverable Codex workflow loops.",
+  "license": "MIT",
+  "author": "tizerluo",
+  "homepage": "https://github.com/tizerluo/HOLO-Codex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tizerluo/HOLO-Codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tizerluo/HOLO-Codex/issues"
+  },
+  "keywords": [
+    "codex",
+    "codex-plugin",
+    "agent",
+    "workflow",
+    "human-on-loop",
+    "observability",
+    "automation"
+  ],
+  "type": "module",
+  "bin": {
+    "agent-loop": "plugins/autonomous-pr-loop/bin/agent-loop.mjs"
+  },
+  "files": [
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "assets/brand/",
+    "docs/checklists/",
+    "docs/examples/",
+    "docs/install.md",
+    "docs/local-release-readiness.md",
+    "docs/release-checklist.md",
+    "docs/self-bootstrap.md",
+    "docs/trust-and-safety.md",
+    ".agents/plugins/marketplace.json",
+    "plugins/autonomous-pr-loop/.codex-plugin/",
+    "plugins/autonomous-pr-loop/.mcp.json",
+    "plugins/autonomous-pr-loop/bin/",
+    "plugins/autonomous-pr-loop/core/",
+    "plugins/autonomous-pr-loop/hooks/",
+    "plugins/autonomous-pr-loop/mcp-server/",
+    "plugins/autonomous-pr-loop/package.json",
+    "plugins/autonomous-pr-loop/schemas/",
+    "plugins/autonomous-pr-loop/scripts/",
+    "plugins/autonomous-pr-loop/skills/",
+    "plugins/autonomous-pr-loop/ui/",
+    "tsconfig.json"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "scripts": {
+    "agent-loop": "tsx plugins/autonomous-pr-loop/scripts/agent-loop.ts",
+    "build:hooks": "esbuild plugins/autonomous-pr-loop/hooks/pre-tool-use.ts plugins/autonomous-pr-loop/hooks/post-tool-use.ts plugins/autonomous-pr-loop/hooks/user-prompt-submit.ts plugins/autonomous-pr-loop/hooks/stop.ts plugins/autonomous-pr-loop/hooks/session-start.ts plugins/autonomous-pr-loop/hooks/pre-compact.ts plugins/autonomous-pr-loop/hooks/post-compact.ts plugins/autonomous-pr-loop/hooks/permission-request.ts --bundle --platform=node --format=esm --outdir=plugins/autonomous-pr-loop/hooks/dist",
+    "prepack": "pnpm build:hooks",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "lucide-react": "^1.17.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsx": "^4.21.0",
+    "vite": "^8.0.16"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.0.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}

package/plugins/autonomous-pr-loop/.codex-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "autonomous-pr-loop",
+  "version": "0.1.0",
+  "description": "Human On Loop Codex control plane for observable, recoverable Codex workflow loops.",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "HOLO-Codex",
+    "shortDescription": "Turn long-running Codex workflows into observable Human On Loop systems.",
+    "longDescription": "A portable Codex plugin for durable workflow state, gates, evidence, hooks, worker orchestration, and the first bundled PR delivery workflow.",
+    "developerName": "tizerluo",
+    "category": "Engineering",
+    "capabilities": ["Write"],
+    "defaultPrompt": ["进入 HOLO-Codex，继续跑到 gate"],
+    "screenshots": ["../../../assets/brand/holo-codex-plugin-card.png"],
+    "brandColor": "#2563EB"
+  }
+}

package/plugins/autonomous-pr-loop/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "autonomous-pr-loop": {
+      "cwd": ".",
+      "command": "pnpm",
+      "args": [
+        "exec",
+        "tsx",
+        "./mcp-server/src/index.ts"
+      ]
+    }
+  }
+}

package/plugins/autonomous-pr-loop/bin/agent-loop.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const script = resolve(packageRoot, "plugins/autonomous-pr-loop/scripts/agent-loop.ts");
+const require = createRequire(import.meta.url);
+const tsxLoader = require.resolve("tsx");
+const child = spawn(process.execPath, ["--import", tsxLoader, script, ...process.argv.slice(2)], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: "inherit"
+});
+
+process.on("SIGINT", () => {});
+process.on("SIGTERM", () => {});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  process.stderr.write(`agent-loop: failed to start CLI runner: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/plugins/autonomous-pr-loop/core/artifacts.ts

@@ -0,0 +1,164 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AgentLoopError } from "./errors.js";
+import { ARTIFACT_KINDS, type ArtifactKind, type ArtifactRecord } from "./state-types.js";
+import type { AgentLoopStorage } from "./types.js";
+
+export interface ArtifactWriter {
+  id: string;
+  path: string;
+  append(content: string | Buffer): void;
+  finalize(): ArtifactRecord;
+}
+
+/** Write a run artifact to disk, persist metadata, and return its record. */
+export function writeArtifact(
+  repoRoot: string,
+  storage: AgentLoopStorage,
+  runId: string,
+  kind: ArtifactKind,
+  name: string,
+  content: string | Buffer
+): ArtifactRecord {
+  assertArtifactKind(kind);
+  const id = randomUUID();
+  const safeName = sanitizeName(name);
+  const path = join(repoRoot, ".agent-loop", "artifacts", runId, kind, safeName);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  const record = {
+    id,
+    runId,
+    kind,
+    name: safeName,
+    path,
+    sha256: sha256(readFileSync(path)),
+    createdAt: new Date().toISOString()
+  };
+  storage.insertArtifact(record);
+  return record;
+}
+
+/** Create an artifact file that can be appended while work is still running. */
+export function createArtifactWriter(
+  repoRoot: string,
+  storage: AgentLoopStorage,
+  runId: string,
+  kind: ArtifactKind,
+  name: string
+): ArtifactWriter {
+  assertArtifactKind(kind);
+  const id = randomUUID();
+  const safeName = sanitizeName(name);
+  const path = join(repoRoot, ".agent-loop", "artifacts", runId, kind, safeName);
+  const hash = createHash("sha256");
+  let finalized: ArtifactRecord | undefined;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, "");
+  return {
+    id,
+    path,
+    append(content: string | Buffer): void {
+      if (finalized) {
+        throw new AgentLoopError("artifact_integrity_error", `Artifact writer is already finalized: ${id}`);
+      }
+      appendFileSync(path, content);
+      hash.update(content);
+    },
+    finalize(): ArtifactRecord {
+      if (finalized) {
+        return finalized;
+      }
+      finalized = {
+        id,
+        runId,
+        kind,
+        name: safeName,
+        path,
+        sha256: hash.digest("hex"),
+        createdAt: new Date().toISOString()
+      };
+      storage.insertArtifact(finalized);
+      return finalized;
+    }
+  };
+}
+
+/** Read an artifact and verify the stored sha256 digest before returning content. */
+export function readArtifact(
+  storage: AgentLoopStorage,
+  artifactId: string
+): { record: ArtifactRecord; content: Buffer } {
+  const record = readArtifactRecord(storage, artifactId);
+  if (!existsSync(record.path)) {
+    throw new AgentLoopError("artifact_integrity_error", `Artifact file is missing: ${record.id}`);
+  }
+  const content = readFileSync(record.path);
+  const actual = sha256(content);
+  if (actual !== record.sha256) {
+    throw new AgentLoopError("artifact_integrity_error", `Artifact sha256 mismatch: ${record.id}`, {
+      details: { expected: record.sha256, actual }
+    });
+  }
+  return { record: toArtifactRecord(record), content };
+}
+
+/** List artifacts for a run. */
+export function listArtifacts(
+  storage: AgentLoopStorage,
+  runId: string
+): ArtifactRecord[] {
+  return storage.listArtifacts(runId).map(toArtifactRecord);
+}
+
+/** Link a persisted artifact id to an event. */
+export function linkArtifactToEvent(
+  storage: AgentLoopStorage,
+  eventId: string,
+  artifactId: string
+): void {
+  storage.linkArtifactToEvent(eventId, artifactId);
+}
+
+function sha256(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function sanitizeName(name: string): string {
+  return name.replaceAll("\\", "/").split("/").filter(Boolean).join("-");
+}
+
+function assertArtifactKind(kind: string): asserts kind is ArtifactKind {
+  if (!(ARTIFACT_KINDS as readonly string[]).includes(kind)) {
+    throw new AgentLoopError("storage_error", `Unsupported artifact kind: ${kind}`);
+  }
+}
+
+function readArtifactRecord(storage: AgentLoopStorage, artifactId: string): ReturnType<AgentLoopStorage["getArtifact"]> {
+  try {
+    return storage.getArtifact(artifactId);
+  } catch (error) {
+    if (error instanceof AgentLoopError) {
+      throw new AgentLoopError("artifact_integrity_error", `Artifact metadata is unavailable: ${artifactId}`, {
+        details: { cause: error.message, code: error.code }
+      });
+    }
+    throw error;
+  }
+}
+
+function toArtifactRecord(record: {
+  id: string;
+  runId: string;
+  kind: string;
+  name: string;
+  path: string;
+  sha256: string;
+  createdAt: string;
+}): ArtifactRecord {
+  return {
+    ...record,
+    kind: record.kind as ArtifactKind
+  };
+}