@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@huynle/hub-cli",
+  "version": "0.7.3",
+  "private": true,
+  "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json"
+  }
+}

package/packages/cli/src/acting.ts

@@ -0,0 +1,70 @@
+// The act verbs in the CLI (design §5, §8): the answer of `hub answer` (key=value pairs, or --json '{…}' / --json -),
+// the short text of what the hub answers to approve, deny, answer, prompt and stop, and the lines a needs_user
+// failure adds (its evaluation and the Decision it opened). The shapes are packages/sdk's types (acting-routes.ts).
+import type { Approved, Denied, Envelope, Evaluation, FormAnswer, FormAnswered, PromptDelivery, Prompted, Stopped } from "../../sdk/src/index.ts"
+import { jsonObjectArg, UsageError, type Parsed } from "./args"
+import { oneLine } from "./format"
+
+const grantText = (grant: string | undefined) => (grant ? `grant ${grant}` : undefined)
+const inParens = (parts: readonly (string | undefined)[]) => {
+  const shown = parts.filter(Boolean)
+  return shown.length ? ` (${shown.join(", ")})` : ""
+}
+
+export const approvedText = (b: Approved): string => `approved ${b.requestID} in ${b.sessionID}${inParens([b.decision, grantText(b.grant)])}`
+
+export function deniedText(b: Denied): string {
+  const reason = b.reasonSent === true ? "; the reason reached the harness" : b.reasonSent === false ? "; the harness did not get the reason (older spoke)" : ""
+  return `denied ${b.requestID} in ${b.sessionID}${inParens([grantText(b.grant)])}${reason}`
+}
+
+export const answeredText = (b: FormAnswered, cancelled: boolean): string => `${cancelled ? "cancelled" : "answered"} ${b.formID} in ${b.sessionID}${inParens([grantText(b.grant)])}`
+
+export function promptedText(b: Prompted): string {
+  if ("messageID" in b) return `prompted ${b.sessionID}: ${b.messageID} delivered (${b.delivered})${b.grant ? `, grant ${b.grant}` : ""}`
+  return `prompted ${b.sessionID}: ${b.mode === "steer" ? "steered into the running turn" : "started a turn"}`
+}
+
+export const stoppedText = (b: Stopped): string => `stopped ${b.sessionID}${inParens([grantText(b.grant)])}`
+
+/** The deliveries of a prompt. */
+export const DELIVERIES: readonly PromptDelivery[] = ["queue", "steer"]
+
+/** The --delivery of `hub prompt`. */
+export function deliveryArg(value: string | undefined): PromptDelivery | undefined {
+  if (value !== undefined && !(DELIVERIES as readonly string[]).includes(value)) throw new UsageError(`--delivery is one of ${DELIVERIES.join(", ")}`)
+  return value as PromptDelivery | undefined
+}
+
+/** The answer of `hub answer`: key=value pairs (a repeated key is a list), or a JSON object from --json; "cancel" for --cancel. */
+export async function formAnswerArg(pairs: readonly string[], flags: Parsed["flags"], stdin: (() => Promise<string>) | undefined): Promise<FormAnswer | "cancel"> {
+  const json = typeof flags.json === "string" ? flags.json : undefined
+  const given = [pairs.length > 0, json !== undefined, flags.cancel === true].filter(Boolean).length
+  if (given > 1) throw new UsageError("give either key=value pairs, --json '{…}' or --cancel")
+  if (flags.cancel === true) return "cancel"
+  if (json !== undefined) return (await jsonObjectArg(json, stdin, "answer")) as FormAnswer
+  if (!pairs.length) throw new UsageError("needs key=value pairs (or --json '{…}', or --cancel)")
+  const answer: Record<string, string | string[]> = {}
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=")
+    if (eq <= 0) throw new UsageError(`answers are key=value (got "${pair}")`)
+    const key = pair.slice(0, eq)
+    const value = pair.slice(eq + 1)
+    const before = answer[key]
+    answer[key] = before === undefined ? value : [...(Array.isArray(before) ? before : [before]), value]
+  }
+  return answer
+}
+
+/** What a needs_user failure adds: the evaluation, the grants checked and the Decision opened for the user. */
+export function needsUserLines(envelope: Envelope): string[] {
+  const lines: string[] = []
+  const evaluation = envelope.evaluation as Evaluation | undefined
+  if (evaluation && typeof evaluation === "object") {
+    lines.push(`evaluation: ${evaluation.verdict}${evaluation.tier ? ` (${evaluation.tier})` : ""} — ${oneLine(String(evaluation.reason ?? ""), 300)}`)
+    const grants = Array.isArray(evaluation.grants) ? evaluation.grants : []
+    lines.push(`grants checked: ${grants.length ? grants.join(", ") : "none"}`)
+  }
+  if (typeof envelope.decisionID === "string") lines.push(`decision ${envelope.decisionID} is open for the user`)
+  return lines
+}

package/packages/cli/src/args.ts

@@ -0,0 +1,91 @@
+// Command-line parsing: `--flag`, `--flag value`, `--flag=value` and short aliases (-n, -h, -V). Unknown flags
+// and wrong positional counts are usage errors (exit 2).
+
+/**
+ * optional: a value only when given with `=` or when the next token starts with a digit (`--wait`, `--wait 30`).
+ * json: a value only when given with `=`, or when the next token looks like JSON (`{`, `[`) or is `-` (stdin):
+ * `hub answer … --json '{…}'` takes the answer while a bare `--json` keeps its usual meaning (raw output).
+ */
+export type FlagKind = "bool" | "string" | "multi" | "optional" | "json"
+
+export interface CommandSpec {
+  readonly flags?: Readonly<Record<string, FlagKind>>
+  /** Positional arguments: required names, then optional ones (suffixed `?`), then any number (suffixed `...`). */
+  readonly args?: readonly string[]
+}
+
+export interface Parsed {
+  readonly flags: Record<string, string | boolean | string[]>
+  readonly args: string[]
+}
+
+export class UsageError extends Error {}
+
+/** Flags every command takes. */
+const COMMON: Record<string, FlagKind> = { json: "bool", help: "bool" }
+const SHORT: Record<string, string> = { h: "help", n: "n", V: "version" }
+
+export function parse(argv: readonly string[], spec: CommandSpec): Parsed {
+  const kinds: Record<string, FlagKind> = { ...COMMON, ...spec.flags }
+  const flags: Parsed["flags"] = {}
+  const args: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!
+    if (token === "--") {
+      args.push(...argv.slice(i + 1))
+      break
+    }
+    const long = /^--([a-z][a-z-]*)(?:=(.*))?$/s.exec(token)
+    const short = /^-([a-zA-Z])$/.exec(token)
+    if (!long && !short) {
+      if (token.startsWith("-") && token.length > 1) throw new UsageError(`unknown option ${token}`)
+      args.push(token)
+      continue
+    }
+    const name = long ? long[1]! : SHORT[short![1]!]
+    const kind = name === undefined ? undefined : kinds[name]
+    if (name === undefined || kind === undefined) throw new UsageError(`unknown option ${token}`)
+    if (kind === "bool") {
+      if (long?.[2] !== undefined) throw new UsageError(`${token}: --${name} takes no value`)
+      flags[name] = true
+      continue
+    }
+    let value = long?.[2]
+    const next = argv[i + 1] ?? ""
+    if (value === undefined && ((kind === "optional" && !/^\d/.test(next)) || (kind === "json" && !/^[{[]/.test(next) && next !== "-"))) {
+      flags[name] = true
+      continue
+    }
+    if (value === undefined) {
+      value = argv[++i]
+      if (value === undefined) throw new UsageError(`--${name} needs a value`)
+    }
+    if (kind === "multi") flags[name] = [...((flags[name] as string[] | undefined) ?? []), value]
+    else flags[name] = value
+  }
+  if (flags.help) return { flags, args }
+  const names = spec.args ?? []
+  const required = names.filter((n) => !n.endsWith("?") && !n.endsWith("...")).length
+  if (args.length < required) throw new UsageError(`missing ${names.slice(args.length, required).join(" ")}`)
+  if (args.length > names.length && !names.at(-1)?.endsWith("...")) throw new UsageError(`unexpected argument ${args[names.length]}`)
+  return { flags, args }
+}
+
+export const str = (flags: Parsed["flags"], name: string): string | undefined => (typeof flags[name] === "string" ? (flags[name] as string) : undefined)
+
+/** A --json value: a JSON object, or all of stdin for "-"; anything else is a usage error. */
+export async function jsonObjectArg(value: string, stdin: (() => Promise<string>) | undefined, what: string): Promise<Record<string, unknown>> {
+  let text = value
+  if (value === "-") {
+    if (!stdin) throw new UsageError(`cannot read the ${what} from stdin here`)
+    text = await stdin()
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    parsed = undefined
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError(`--json takes the ${what} as a JSON object`)
+  return parsed as Record<string, unknown>
+}

package/packages/cli/src/bootstrap/adapters/archive-stream.ts

@@ -0,0 +1,276 @@
+// Streaming readers for the release archives harness adapters unpack (OpenCode's tar.gz and zip, Codex's tar.gz),
+// so an archive and what it unpacks to are never in memory whole: gzip and raw deflate through hub's own streaming
+// decoder (inflate.ts), tar parsed block by block from the inflated stream, zip members located through the central
+// directory and inflated by offset. Each reader only reports what the archive says; the adapters decide what is acceptable
+// (names, types, layout) before a member's body is written anywhere. Limits are enforced while streaming: the
+// inflated total (a gzip bomb stops at `maxBytes`), and a zip member never inflates past its recorded size.
+// No dependency.
+import type { ByteReader } from "../transaction/stream.ts"
+import { crc32, gunzipChunks, InflateError, inflateRawChunks } from "./inflate.ts"
+
+/** Why an archive was refused (the adapters phrase it). */
+export class ArchiveError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ArchiveError"
+  }
+}
+
+const BLOCK = 512
+
+const field = (block: Uint8Array, at: number, len: number) => {
+  const raw = block.subarray(at, at + len)
+  const end = raw.indexOf(0)
+  return new TextDecoder().decode(end < 0 ? raw : raw.subarray(0, end))
+}
+
+/** An octal tar number, or GNU base-256 (high bit set) for large sizes; undefined when unreadable. */
+function tarNumber(block: Uint8Array, at: number, len: number): number | undefined {
+  if (block[at]! & 0x80) {
+    let n = 0
+    for (let i = at + 1; i < at + len; i++) n = n * 256 + block[i]!
+    return Number.isSafeInteger(n) ? n : undefined
+  }
+  const text = field(block, at, len).trim()
+  if (text === "") return 0
+  return /^[0-7]+$/.test(text) ? parseInt(text, 8) : undefined
+}
+
+function checksumOK(block: Uint8Array): boolean {
+  let sum = 0
+  for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 0x20 : block[i]!
+  return tarNumber(block, 148, 8) === sum
+}
+
+/** Pulls exact byte counts out of a chunked stream, counting everything it pulls against a limit. */
+class Pull {
+  private chunk: Uint8Array = new Uint8Array()
+  private at = 0
+  private total = 0
+  constructor(
+    private readonly source: Iterator<Uint8Array>,
+    private readonly maxBytes: number,
+    private readonly overLimit: string,
+    private readonly damaged: string,
+  ) {}
+
+  private async more(): Promise<boolean> {
+    let next: IteratorResult<Uint8Array>
+    try {
+      next = this.source.next()
+    } catch (error) {
+      if (error instanceof InflateError) throw new ArchiveError(`${this.damaged} (${error.message})`)
+      throw error
+    }
+    if (next.done) return false
+    this.total += next.value.byteLength
+    if (this.total > this.maxBytes) throw new ArchiveError(this.overLimit)
+    this.chunk = next.value
+    this.at = 0
+    return true
+  }
+
+  /** Exactly `n` bytes (a header), or undefined at a clean end of the stream before any of them. */
+  async exact(n: number): Promise<Uint8Array | undefined> {
+    const out = new Uint8Array(n)
+    let got = 0
+    while (got < n) {
+      if (this.at >= this.chunk.byteLength && !(await this.more())) {
+        if (got === 0) return undefined
+        throw new ArchiveError("it is truncated")
+      }
+      const take = Math.min(n - got, this.chunk.byteLength - this.at)
+      out.set(this.chunk.subarray(this.at, this.at + take), got)
+      this.at += take
+      got += take
+    }
+    return out
+  }
+
+  /** The next `n` bytes, as the chunks they arrive in. */
+  async *take(n: number): AsyncGenerator<Uint8Array> {
+    let left = n
+    while (left > 0) {
+      if (this.at >= this.chunk.byteLength && !(await this.more())) throw new ArchiveError("it is truncated")
+      const take = Math.min(left, this.chunk.byteLength - this.at)
+      const part = this.chunk.subarray(this.at, this.at + take)
+      this.at += take
+      left -= take
+      yield part
+    }
+  }
+
+  async skip(n: number): Promise<void> {
+    for await (const _ of this.take(n));
+  }
+}
+
+export interface TarHeader {
+  /** The member name as the header has it (ustar prefix joined), before pax or GNU long names. */
+  readonly name: string
+  /** The type flag; a NUL flag reads as "0". */
+  readonly type: string
+  readonly size: number
+  /** The permission bits field, when readable. */
+  readonly mode: number | undefined
+}
+
+export interface TarMember {
+  readonly header: TarHeader
+  /** The member's data, in chunks (once; what is not read is skipped). */
+  body(): AsyncGenerator<Uint8Array>
+  /** A small member's data whole (pax and GNU long-name records); ArchiveError beyond `limit`. */
+  bytes(limit: number): Promise<Uint8Array>
+}
+
+/**
+ * Reads a gzipped tar from `reader`, calling `visit` for each member in order until the end marker. `visit` may
+ * refuse (throw ArchiveError) before reading the body. ArchiveError for a damaged, truncated or oversized archive:
+ * `maxBytes` bounds the inflated stream, and the limit is enforced as it inflates.
+ */
+export async function readTarGz(reader: ByteReader, options: { readonly maxBytes: number }, visit: (member: TarMember) => Promise<void>): Promise<void> {
+  const iterator = gunzipChunks(reader)
+  const pull = new Pull(iterator, options.maxBytes, `it inflates beyond ${options.maxBytes} bytes`, "it is not a gzip stream (or it is damaged)")
+  try {
+    for (;;) {
+      const block = await pull.exact(BLOCK)
+      if (!block) throw new ArchiveError("a tar without its end marker")
+      if (block.every((b) => b === 0)) return
+      if (!checksumOK(block)) throw new ArchiveError("a header checksum does not match")
+      const size = tarNumber(block, 124, 12)
+      if (size === undefined) throw new ArchiveError("a header has an unreadable size")
+      const magic = field(block, 257, 6)
+      const prefix = magic.startsWith("ustar") && magic !== "ustar " ? field(block, 345, 155) : ""
+      const name = prefix ? `${prefix}/${field(block, 0, 100)}` : field(block, 0, 100)
+      const flag = block[156]!
+      const header: TarHeader = { name, type: flag === 0 ? "0" : String.fromCharCode(flag), size, mode: tarNumber(block, 100, 8) }
+      let consumed = false
+      const body = async function* () {
+        if (consumed) throw new Error("a tar member's body is read once")
+        consumed = true
+        yield* pull.take(size)
+      }
+      await visit({
+        header,
+        body,
+        async bytes(limit) {
+          if (size > limit) throw new ArchiveError(`a ${header.type} record is larger than ${limit} bytes`)
+          const out = new Uint8Array(size)
+          let at = 0
+          for await (const part of body()) {
+            out.set(part, at)
+            at += part.byteLength
+          }
+          return out
+        },
+      })
+      if (!consumed) await pull.skip(size)
+      await pull.skip((BLOCK - (size % BLOCK)) % BLOCK)
+    }
+  } finally {
+    iterator.return(undefined)
+  }
+}
+
+// ---------- zip ----------
+
+export interface ZipMember {
+  readonly name: string
+  readonly kind: "file" | "directory" | "other"
+  readonly encrypted: boolean
+  readonly method: number
+  readonly compressedSize: number
+  readonly size: number
+  /** The CRC-32 the directory records for the member's data. */
+  readonly crc32: number
+  /** The local header's offset. */
+  readonly local: number
+}
+
+/** The members a zip's central directory lists (zip64 is refused); ArchiveError when it is not a readable zip. */
+export function zipMembers(reader: ByteReader, options: { readonly maxBytes: number; readonly maxEntries?: number }): ZipMember[] {
+  const tailStart = Math.max(0, reader.size - 22 - 0xffff)
+  const tail = reader.read(tailStart, reader.size - tailStart)
+  const tv = new DataView(tail.buffer, tail.byteOffset, tail.byteLength)
+  let eocd = -1
+  for (let i = tail.byteLength - 22; i >= 0; i--)
+    if (tv.getUint32(i, true) === 0x06054b50) {
+      eocd = i
+      break
+    }
+  if (eocd < 0) throw new ArchiveError("not a zip archive")
+  const count = tv.getUint16(eocd + 10, true)
+  const cdSize = tv.getUint32(eocd + 12, true)
+  const cdOffset = tv.getUint32(eocd + 16, true)
+  if (count === 0xffff || cdOffset === 0xffffffff || cdOffset + cdSize > tailStart + eocd) throw new ArchiveError("an unsupported or damaged zip (zip64 or bad directory)")
+  if (count > (options.maxEntries ?? 10_000) || cdSize > 16 * 1024 * 1024) throw new ArchiveError("a zip directory larger than any release has")
+  const cd = reader.read(cdOffset, cdSize)
+  const view = new DataView(cd.buffer, cd.byteOffset, cd.byteLength)
+  const decoder = new TextDecoder("utf-8", { fatal: true })
+  const members: ZipMember[] = []
+  let at = 0
+  let total = 0
+  for (let n = 0; n < count; n++) {
+    if (at + 46 > cd.byteLength || view.getUint32(at, true) !== 0x02014b50) throw new ArchiveError("a damaged zip directory")
+    const flags = view.getUint16(at + 8, true)
+    const method = view.getUint16(at + 10, true)
+    const crc = view.getUint32(at + 16, true)
+    const compressedSize = view.getUint32(at + 20, true)
+    const size = view.getUint32(at + 24, true)
+    const nameLen = view.getUint16(at + 28, true)
+    const extraLen = view.getUint16(at + 30, true)
+    const commentLen = view.getUint16(at + 32, true)
+    const madeBy = view.getUint8(at + 5)
+    const external = view.getUint32(at + 38, true)
+    const local = view.getUint32(at + 42, true)
+    if (at + 46 + nameLen > cd.byteLength) throw new ArchiveError("a damaged zip directory")
+    let name: string
+    try {
+      name = decoder.decode(cd.subarray(at + 46, at + 46 + nameLen))
+    } catch {
+      throw new ArchiveError("a member name that is not UTF-8")
+    }
+    at += 46 + nameLen + extraLen + commentLen
+    const type = madeBy === 3 ? (external >>> 16) & 0o170000 : name.endsWith("/") ? 0o040000 : 0o100000
+    const kind = type === 0o040000 ? "directory" : type === 0o100000 ? "file" : "other"
+    if (kind === "file") {
+      total += size
+      if (total > options.maxBytes) throw new ArchiveError(`it unpacks to more than ${options.maxBytes} bytes`)
+    }
+    members.push({ name, kind, encrypted: (flags & 0x1) !== 0, method, compressedSize, size, crc32: crc, local })
+  }
+  return members
+}
+
+/**
+ * One zip member's data, inflated as it streams, in chunks; ArchiveError if it is damaged, uses an unsupported
+ * method, does not inflate to exactly its recorded size (it is cut off at that size, never past it), or does not
+ * have its recorded CRC-32 (checked once the last chunk is out: the caller discards what it wrote).
+ */
+export async function* zipMemberData(reader: ByteReader, member: ZipMember): AsyncGenerator<Uint8Array> {
+  if (member.encrypted) throw new ArchiveError(`${member.name} is encrypted`)
+  if (member.method !== 0 && member.method !== 8) throw new ArchiveError(`${member.name} uses an unsupported compression method (${member.method})`)
+  const header = reader.read(member.local, 30)
+  const hv = new DataView(header.buffer, header.byteOffset, header.byteLength)
+  if (header.byteLength < 30 || hv.getUint32(0, true) !== 0x04034b50) throw new ArchiveError("a damaged zip member")
+  const start = member.local + 30 + hv.getUint16(26, true) + hv.getUint16(28, true)
+  if (start + member.compressedSize > reader.size) throw new ArchiveError("a truncated zip")
+  let produced = 0
+  let crc = 0
+  const wrongSize = () => new ArchiveError(`${member.name} does not have its recorded size`)
+  try {
+    const chunks = member.method === 0 ? reader.stream(start, start + member.compressedSize) : inflateRawChunks(reader, start, start + member.compressedSize).chunks
+    for await (const chunk of chunks) {
+      produced += chunk.byteLength
+      if (produced > member.size) throw wrongSize()
+      crc = crc32(crc, chunk)
+      yield chunk
+    }
+  } catch (error) {
+    if (error instanceof InflateError) throw new ArchiveError(`${member.name} does not decompress (${error.message})`)
+    throw error
+  }
+  if (produced !== member.size) throw wrongSize()
+  if (crc !== member.crc32) throw new ArchiveError(`${member.name} does not have its recorded CRC-32`)
+}
+

package/packages/cli/src/bootstrap/adapters/claude/README.md

@@ -0,0 +1,63 @@
+# Claude Code bootstrap adapter (HBS-08)
+
+This adapter plans, installs and verifies Claude Code for `hubctl setup`. It implements contracts §3.6.1, §3.10 and
+§5 of `docs/bootstrap-contracts.md`. It is a pure planner. It reaches outside itself only through injected ports,
+and it never gets a shell.
+
+| File | Role |
+|---|---|
+| `adapter.ts` | `createClaudeAdapter` (a `HarnessAdapter`) and `planClaude`. Plans, in order: pinned `install-harness`, `select-harness-version`, `merge-config` of hub's own `config:hub/claude-code.json`, `verify-harness`. Also `discover()` and `binary()`, both through the read-only `DiscoveryProbe`. |
+| `source.ts` | `createClaudeHarnessSource`, the `HarnessSource` for `installHarnessExecutor`. It streams the pinned file into the step's staging area, records the optional evidence (against the staged digest; codesign on a scratch copy written in chunks) and installs the staged binary itself as `<version>/claude`. |
+| `openpgp.ts` | An in-house check of a detached OpenPGP v4 RSA signature. It verifies upstream's signed `manifest.json` against the pinned release key and needs no `gpg`. |
+| `verify.ts` | The real readiness probes, `claudeReadiness` (the capability is offered only when the harness is ready) and `claudeVerifyExecutor`. |
+| `ports.ts` / `node.ts` | The injected ports (`Downloader`, `ProbeRunner`, `Scratch`) and their Node defaults (`httpsDownloader`, `nodeRunner`, `tempScratch`). |
+| `index.ts` | Re-exports, and `claudeExecutors`: `install-harness` and `verify-harness` for claude-code. |
+
+## Authenticity
+
+The mandatory check is the sha256 that hub's signed manifest pins. `installHarnessExecutor` checks it first,
+through `checkHarnessEvidence`. The optional evidence is then recorded as `verified`, `unavailable` or `failed`.
+Any `failed` result rejects the artifact.
+
+- **`gpg-manifest`.** The adapter fetches `…/claude-code-releases/<v>/manifest.json`, its `.sig`, and
+  `https://downloads.claude.ai/keys/claude-code.asc`. The key's fingerprint must be
+  `31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE` (`CLAUDE_SIGNING_FINGERPRINT`). The signature is a v4 RSA signature
+  over a binary document, using SHA-2.
+  - `verified`: the signature is good, and the signed manifest lists exactly the pinned version, checksum and size
+    for this platform.
+  - `failed`: the signature does not verify, the signature is malformed, or the signed manifest lists other bytes
+    or another version.
+  - `unavailable`: there is no signature (releases before 2.1.89), the bucket cannot be reached, the key is
+    another one or a rotated one, the format is unsupported, or the pin URL is outside upstream's bucket.
+- **`macos-notarization`.** This check runs on macOS only. It runs `/usr/bin/codesign --verify --strict` (fixed
+  argv) on a private copy of the downloaded bytes.
+  - It first checks `-R=anchor apple generic and certificate leaf[subject.OU] = "Q6L2SF6YDW"`, which means signed
+    by Anthropic PBC. If this fails, the result is `failed`.
+  - It then checks `-R=notarized and …`. If this passes, the result is `verified`. If it fails, the result is
+    `unavailable`, because the ticket may not be confirmable offline.
+  - The result is also `unavailable` when codesign is missing, when the host is not macOS, or when the target is
+    Linux.
+
+## User config and credentials
+
+- No plan ever touches `~/.claude` or `~/.claude.json`. The existing integration loads the hub plugin with
+  `--plugin-dir` (`packages/claude-code/src/wrapper.ts`).
+- The only config hub edits is its own `config:hub/claude-code.json`, and only the key `/binary`. The edit is
+  lossless and pinned by a precondition. A rollback removes the file, or restores it if it existed before.
+- Logins are user-mediated (`claude auth login`). `provider-auth` runs `claude auth status`, reads only its exit
+  code and `authMethod`, and drops the rest of the output. The child gets the user's environment minus `HUB_*` and
+  `BUN_BE_BUN`. `version-exec` gets only `PATH`, `HOME` and the update switches.
+
+## Pin template for `release/harness-pins.json` (fill in from a fresh re-download; never copy digests from here)
+
+```json
+{ "pin": { "harness": "claude-code", "version": "<exact, e.g. the stable channel's>", "target": "darwin-arm64",
+           "url": "https://downloads.claude.ai/claude-code-releases/<version>/darwin-arm64/claude",
+           "file": "claude", "size": <bytes>, "sha256": "sha256:<hex of the re-downloaded file>",
+           "evidence": ["gpg-manifest", "macos-notarization"], "minimumVersion": "2.1.89" },
+  "review": { "by": "<handle>", "on": "<date>", "checked": ["upstream-release", "digest-redownloaded", "evidence-listed"] } }
+```
+
+- Pins for `linux-x64` and `linux-arm64` list `"evidence": ["gpg-manifest"]`. Linux binaries are not codesigned.
+- `minimumVersion` 2.1.89 is the first release with a signed manifest.
+- `file` must be `claude`, upstream's raw binary. The `.zst` variant is refused by `unpack`.