@agentsfleet/orly 0.10.13 → 0.11.0

package/src/installation/migration.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, expect, test } from "bun:test";
+import { join } from "node:path";
+import { CONFIG_PATH, contentDigest, readConfig } from "../config";
+import { cleanupTemporaryDirectories, newRepository, temporaryDirectory } from "../gates_test_support";
+import { install } from "../install";
+import { RulesModel } from "../model";
+import { AGENTS_FILENAME } from "../loaders";
+import { PREVIOUS_CONFIG } from "./migration";
+import { HOOKS_DIRECTORY, hooksPath } from "./hooks";
+import type { FileWrite } from "./transaction";
+import { UNSCOPED_ENVIRONMENT } from "../git_env";
+import { chmodSync } from "node:fs";
+
+const OLD_RULE = "dispatch/check.md";
+const OLD_AGENTS = "AGENTS.orly.md";
+const OWNER_RULES = "# Owner rules\nKeep this instruction.\n";
+const OLD_BODY = "old managed content\n";
+const OWNER_NOTE = ".oracle/owner-note";
+const UNOWNED_BODY = "unowned state\n";
+const CURRENT_RULE = ".orly/dispatch/check.md";
+const CONTENT_ENCODING = "base64";
+const VERSION = "0.12.0";
+const JOURNAL = ".orly/install-journal.json";
+const WRITE_COUNT = 6;
+const HOOK_WRITE_COUNT = 8;
+const JOURNAL_STAGE = "journal";
+const WRITE_STAGE = "write";
+const DELETE_STAGE = "delete";
+const METADATA_STAGE = "metadata";
+const INTERRUPTION = "injected interruption";
+const OWNER_HOOKS = ".owner-hooks";
+const OPENCODE = "opencode.json";
+const OWNER_DOCUMENT = "owner.md";
+const STEPS: Array<[string, number]> = [
+  [JOURNAL_STAGE, 0], ...Array.from({ length: WRITE_COUNT }, (_, index): [string, number] => [WRITE_STAGE, index]),
+  [METADATA_STAGE, 0], [DELETE_STAGE, 0], [DELETE_STAGE, 1], [DELETE_STAGE, 2],
+];
+const HOOK_STEPS: Array<[string, number]> = [
+  [JOURNAL_STAGE, 0], ...Array.from({ length: HOOK_WRITE_COUNT }, (_, index): [string, number] => [WRITE_STAGE, index]),
+  [METADATA_STAGE, 0], [DELETE_STAGE, 0], [DELETE_STAGE, 1], [DELETE_STAGE, 2],
+];
+
+afterEach(cleanupTemporaryDirectories);
+
+test.each([".git/hooks", ".githooks"])("an active owner hook in %s remains connected", async (directory) => {
+  const { repo, model, options } = await fixture();
+  const path = join(repo, directory, "commit-msg");
+  const owner = "#!/bin/sh\nexit 0\n";
+  await Bun.write(path, owner);
+  chmodSync(path, 0o755);
+  if (directory === ".githooks") {
+    const config = await Bun.file(join(repo, PREVIOUS_CONFIG)).json();
+    config.managed.push(".githooks/pre-commit", ".githooks/pre-push");
+    await Bun.write(join(repo, PREVIOUS_CONFIG), JSON.stringify(config));
+    expect(Bun.spawnSync(["git", "-C", repo, "config", "core.hooksPath", directory]).exitCode).toBe(0);
+  }
+  const before = hooksPath(repo);
+  const result = await install(model, { ...options, installHooks: true });
+  expect(result.ok).toBe(false);
+  expect(result.errors.map((error) => error.message).join("\n")).toContain("--no-hooks");
+  expect(hooksPath(repo)).toBe(before);
+  expect(await Bun.file(path).text()).toBe(owner);
+  expect((await install(model, options)).ok).toBe(true);
+  expect(hooksPath(repo)).toBe(before);
+  expect(await Bun.file(path).text()).toBe(owner);
+});
+
+async function fixture() {
+  const repo = newRepository();
+  const engine = temporaryDirectory();
+  await Bun.write(join(engine, "core.md"), "new operating model\n");
+  await Bun.write(join(engine, "guide.md"), "new managed guide\n");
+  const model = new RulesModel(engine, { core_documents: ["core.md"], packs: { base: { extensions: [], managed_files: [{ source: "guide.md", target: OLD_RULE }] } }, rules: [] });
+  await Bun.write(join(repo, OLD_RULE), OLD_BODY);
+  await Bun.write(join(repo, OLD_AGENTS), OLD_BODY);
+  await Bun.write(join(repo, AGENTS_FILENAME), OWNER_RULES);
+  await Bun.write(join(repo, PREVIOUS_CONFIG), JSON.stringify({
+    schema_version: 1, orly_version: "0.11.0", packs: [], commands: { conform: [["true"]], "verify.unit": [["true"]] },
+    managed: [OLD_RULE, OLD_AGENTS], digests: { [OLD_RULE]: contentDigest(Buffer.from(OLD_BODY)), [OLD_AGENTS]: contentDigest(Buffer.from(OLD_BODY)) },
+  }));
+  await Bun.write(join(repo, OWNER_NOTE), UNOWNED_BODY);
+  return { repo, model, options: { targetRoot: repo, force: false, installHooks: false, orlyVersion: VERSION } };
+}
+
+test.each(STEPS)("interrupted_install_recovers at %s %d", async (stage, ordinal) => {
+  await recoverInterruptedFixture(stage, ordinal, false, WRITE_COUNT);
+});
+
+test.each(HOOK_STEPS)("hook installation recovers interruption at %s %d", async (stage, ordinal) => {
+  await recoverInterruptedFixture(stage, ordinal, true, HOOK_WRITE_COUNT);
+});
+
+async function recoverInterruptedFixture(stage: string, ordinal: number, installHooks: boolean, writeCount: number) {
+  const { repo, model, options } = await fixture();
+  options.installHooks = installHooks;
+  const previous = await Bun.file(join(repo, PREVIOUS_CONFIG)).text();
+  let injected = 0;
+  const result = await install(model, { ...options, checkpoint: (current, index) => {
+    if (current === stage && index === ordinal) { injected++; throw new Error(INTERRUPTION); }
+  } });
+  expect(injected).toBe(1);
+  expect(result.ok).toBe(false);
+  expect(result.errors.map((error) => error.message)).toEqual([INTERRUPTION]);
+  await expectInterruptedState(repo, stage, ordinal, previous, writeCount);
+  const configured = installHooks && (stage === METADATA_STAGE || stage === DELETE_STAGE);
+  expect(hooksPath(repo)).toBe(configured ? HOOKS_DIRECTORY : null);
+  expect((await install(model, options)).errors).toEqual([]);
+  expect(await Bun.file(join(repo, CURRENT_RULE)).text()).toBe("new managed guide\n");
+  expect(await Bun.file(join(repo, AGENTS_FILENAME)).text()).toStartWith(OWNER_RULES.trim());
+  expect(await Bun.file(join(repo, OWNER_NOTE)).text()).toBe(UNOWNED_BODY);
+  for (const path of [OLD_RULE, OLD_AGENTS, PREVIOUS_CONFIG, JOURNAL]) expect(await Bun.file(join(repo, path)).exists()).toBe(false);
+  expect((await readConfig(repo))?.orly_version).toBe(VERSION);
+  expect(hooksPath(repo)).toBe(installHooks ? HOOKS_DIRECTORY : null);
+  expect((await install(model, options)).written).toEqual([]);
+}
+
+async function expectInterruptedState(repo: string, stage: string, ordinal: number, previous: string, writeCount: number): Promise<void> {
+  const journal: { data: { writes: FileWrite[] } } = await Bun.file(join(repo, JOURNAL)).json();
+  expect(journal.data.writes).toHaveLength(writeCount);
+  const written = stage === JOURNAL_STAGE ? 0 : stage === WRITE_STAGE ? ordinal + 1 : writeCount;
+  for (const [index, file] of journal.data.writes.entries()) {
+    const current = Bun.file(join(repo, file.path));
+    if (index < written) expect(await current.bytes()).toEqual(Buffer.from(file.content, CONTENT_ENCODING));
+    else if (file.before === null) expect(await current.exists()).toBe(false);
+    else expect(contentDigest(await current.bytes())).toBe(file.before);
+  }
+  expect((await readConfig(repo))?.orly_version).toBe(written === writeCount ? VERSION : undefined);
+  const obsolete: Array<[string, string]> = [[OLD_RULE, OLD_BODY], [OLD_AGENTS, OLD_BODY], [PREVIOUS_CONFIG, previous]];
+  for (const [index, [path, bytes]] of obsolete.entries()) {
+    const deleted = stage === DELETE_STAGE && index <= ordinal;
+    expect(await Bun.file(join(repo, path)).exists()).toBe(!deleted);
+    if (!deleted) expect(await Bun.file(join(repo, path)).text()).toBe(bytes);
+  }
+  expect(await Bun.file(join(repo, OWNER_NOTE)).text()).toBe(UNOWNED_BODY);
+  expect(await Bun.file(join(repo, AGENTS_FILENAME)).text()).toStartWith(OWNER_RULES.trim());
+}
+
+test.each([OLD_RULE, OLD_AGENTS, CURRENT_RULE])("migration_preserves_owned_content refuses edited or unowned %s", async (path) => {
+  const { repo, model, options } = await fixture();
+  const correction = "owner correction\n";
+  await Bun.write(join(repo, path), correction);
+  const before = await Bun.file(join(repo, PREVIOUS_CONFIG)).text();
+  expect((await install(model, options)).ok).toBe(false);
+  expect(await Bun.file(join(repo, path)).text()).toBe(correction);
+  expect(await Bun.file(join(repo, PREVIOUS_CONFIG)).text()).toBe(before);
+  expect(await Bun.file(join(repo, ".orly/orly.json")).exists()).toBe(false);
+});
+
+test("recovery refuses an edited destination before deleting any old source", async () => {
+  const { repo, model, options } = await fixture();
+  await install(model, { ...options, checkpoint: (stage) => { if (stage === "metadata") throw new Error("interruption"); } });
+  await Bun.write(join(repo, CURRENT_RULE), "concurrent owner correction\n");
+  await expect(install(model, options)).rejects.toThrow("changed after planning");
+  expect(await Bun.file(join(repo, OLD_RULE)).text()).toBe(OLD_BODY);
+  expect(await Bun.file(join(repo, PREVIOUS_CONFIG)).exists()).toBe(true);
+});
+
+test("changed journal cannot authorize recovery", async () => {
+  const { repo, model, options } = await fixture();
+  await install(model, { ...options, checkpoint: () => { throw new Error("interruption"); } });
+  const journal = await Bun.file(join(repo, JOURNAL)).json();
+  journal.data.deletes = [];
+  await Bun.write(join(repo, JOURNAL), JSON.stringify(journal));
+  await expect(install(model, options)).rejects.toThrow("integrity mismatch");
+  expect(await Bun.file(join(repo, OLD_RULE)).text()).toBe(OLD_BODY);
+});
+
+test("a current installation preserves an independent previous configuration", async () => {
+  const { repo, model, options } = await fixture();
+  const independent = await Bun.file(join(repo, PREVIOUS_CONFIG)).text();
+  await Bun.write(join(repo, CONFIG_PATH), JSON.stringify({ schema_version: 1, packs: [], managed: [], digests: {}, commands: {} }));
+  expect((await install(model, options)).ok).toBe(true);
+  expect(await Bun.file(join(repo, PREVIOUS_CONFIG)).text()).toBe(independent);
+  expect(await Bun.file(join(repo, OLD_RULE)).text()).toBe(OLD_BODY);
+});
+
+test.each([true, false])("recovery preserves an owner-changed hooks setting with resumed hooks %s", async (installHooks) => {
+  const { repo, model, options } = await fixture();
+  const interrupted = await install(model, { ...options, installHooks: true, checkpoint: (stage) => {
+    if (stage === "journal") throw new Error("interrupt before hook configuration");
+  } });
+  expect(interrupted.ok).toBe(false);
+  const changed = Bun.spawnSync(["git", "config", "core.hooksPath", OWNER_HOOKS], { cwd: repo, env: UNSCOPED_ENVIRONMENT });
+  expect(changed.exitCode).toBe(0);
+  await expect(install(model, { ...options, installHooks })).rejects.toThrow("hooks setting changed");
+  const current = Bun.spawnSync(["git", "config", "--get", "core.hooksPath"], { cwd: repo, env: UNSCOPED_ENVIRONMENT, stdout: "pipe" });
+  expect(current.stdout.toString().trim()).toBe(OWNER_HOOKS);
+  expect(await Bun.file(join(repo, OLD_RULE)).text()).toBe(OLD_BODY);
+});
+
+test("owner hook changes during destination writes are refused before metadata or cleanup", async () => {
+  const { repo, model, options } = await fixture();
+  const result = await install(model, { ...options, installHooks: true, checkpoint: (stage, index) => {
+    if (stage === WRITE_STAGE && index === HOOK_WRITE_COUNT - 1) {
+      const changed = Bun.spawnSync(["git", "config", "core.hooksPath", OWNER_HOOKS], { cwd: repo, env: UNSCOPED_ENVIRONMENT });
+      expect(changed.exitCode).toBe(0);
+    }
+  } });
+  expect(result.ok).toBeFalse();
+  expect(result.errors.map((error) => error.message)).toEqual(["installation conflict: hooks setting changed after planning"]);
+  expect(hooksPath(repo)).toBe(OWNER_HOOKS);
+  expect(await Bun.file(join(repo, OLD_RULE)).text()).toBe(OLD_BODY);
+  expect(await Bun.file(join(repo, PREVIOUS_CONFIG)).exists()).toBeTrue();
+  expect(await Bun.file(join(repo, JOURNAL)).exists()).toBeTrue();
+});
+
+test("migration removes only proven obsolete instruction references", async () => {
+  const { repo, model, options } = await fixture();
+  await Bun.write(join(repo, OPENCODE), JSON.stringify({ instructions: [OLD_AGENTS, OWNER_DOCUMENT] }));
+  expect((await install(model, options)).ok).toBe(true);
+  expect((await Bun.file(join(repo, OPENCODE)).json()).instructions).toEqual([OWNER_DOCUMENT, "AGENTS.md", ".orly/AGENTS.md"]);
+});

package/src/installation/migration.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_PATH, contentDigest, parseConfig, readConfig, sameDigest, type RepoConfig } from "../config";
+import { assertWritableInside, OrlyError } from "../model";
+import { HOOK_INVOCATION_ENV, HOOK_INVOCATION_VALUE } from "../telemetry";
+import type { FileDelete } from "./transaction";
+
+export const PREVIOUS_CONFIG = ".oracle/orly.json";
+const TEXT_ENCODING = "utf8";
+
+// Only installation may read the old location. Gates require the current one.
+export async function readInstallConfig(root: string): Promise<RepoConfig | undefined> {
+  const current = await readConfig(root);
+  if (current) return current;
+  assertWritableInside(root, PREVIOUS_CONFIG, "migration configuration");
+  const path = join(root, PREVIOUS_CONFIG);
+  if (!existsSync(path)) return undefined;
+  return parseConfig(JSON.parse(readFileSync(path, TEXT_ENCODING)));
+}
+
+export function migrationDeletes(root: string, config: RepoConfig, destinations: Set<string>): FileDelete[] {
+  const deletes: FileDelete[] = [];
+  for (const path of config.managed) {
+    if (destinations.has(path) || path === "AGENTS.md") continue;
+    assertWritableInside(root, path, "migration source");
+    if (!existsSync(join(root, path))) continue;
+    const current = contentDigest(readFileSync(join(root, path)));
+    const recorded = config.digests[path] ?? previousHookDigest(root, path);
+    if (!recorded || !sameDigest(recorded, current)) throw new OrlyError(`migration conflict: ${path} lacks matching recorded ownership; preserve or reconcile it before updating`);
+    deletes.push({ path, before: current });
+  }
+  if (!existsSync(join(root, CONFIG_PATH)) && existsSync(join(root, PREVIOUS_CONFIG))) {
+    deletes.push({ path: PREVIOUS_CONFIG, before: contentDigest(readFileSync(join(root, PREVIOUS_CONFIG))) });
+  }
+  return deletes;
+}
+
+function previousHookDigest(root: string, path: string): string | undefined {
+  const gate = path === ".githooks/pre-commit" ? "work" : path === ".githooks/pre-push" ? "verify" : undefined;
+  if (!gate) return undefined;
+  const content = readFileSync(join(root, path));
+  return content.toString(TEXT_ENCODING) === previousHookScript(gate) ? contentDigest(content) : undefined;
+}
+
+function previousHookScript(gate: string): string {
+  return [
+    "#!/usr/bin/env bash",
+    "# Generated by orly. Re-run `orly init` to refresh.",
+    "set -euo pipefail",
+    "",
+    "# git exports these to every hook; inherited by a spawned git they pin it to",
+    "# the hook's repository instead of the one being judged.",
+    "unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX \\",
+    "      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "",
+    'if ! command -v orly >/dev/null 2>&1; then',
+    "    printf '%s\\n' 'orly: not on PATH — install it with `bun add -g @agentsfleet/orly`' >&2",
+    "    exit 1",
+    "fi",
+    "",
+    `export ${HOOK_INVOCATION_ENV}=${HOOK_INVOCATION_VALUE}`,
+    `exec orly gate ${gate}`,
+    "",
+  ].join("\n");
+}

package/src/installation/plan.ts

@@ -0,0 +1,96 @@
+import { realpathSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { isString, modeLabel, objectArray, objectValue, OrlyError, type RulesModel } from "../model";
+import { AGENTS_FILENAME, ORLY_AGENTS_FILENAME, type Layout } from "../loaders";
+import { renderProfileText } from "../references";
+import { Renderer } from "../render";
+
+const REGISTRY_PACKS_LABEL = "registry packs";
+const MARKDOWN_EXTENSION = ".md";
+const SKILLS_SEGMENT = "/skills/";
+const MODE_REGULAR = "0644";
+export type PlannedFile = { target: string; content: Uint8Array; mode: string };
+
+export function installedPath(target: string): string {
+  if (target.startsWith(".orly/")) return target;
+  if (target.includes(SKILLS_SEGMENT)) return `.orly/skills/${target.split(SKILLS_SEGMENT)[1]}`;
+  return `.orly/${target}`;
+}
+
+function installedReferences(text: string, paths: Set<string>): string {
+  return text.replaceAll("`../.orly/AGENTS.md`", "`../AGENTS.md`").replaceAll("](../.orly/AGENTS.md)", "](../AGENTS.md)")
+    .replaceAll("](.orly/AGENTS.md)", "](AGENTS.md)")
+    .replace(/(?<![\w./-])(dispatch|audits)\//g, ".orly/$1/")
+    .replace(/(?<![\w./-])docs\/(?:greptile-learnings\/[^\s`)'"]+|[A-Z][A-Z_0-9.]+\.md)/g, (path) => paths.has(path) ? `.orly/${path}` : path);
+}
+
+// One entry per target, so two packs naming the same file collapse instead of
+// racing. Two packs naming DIFFERENT sources for one target is a registry bug
+// and stops the install rather than letting pack order decide the winner.
+export async function planFiles(model: RulesModel, packs: string[], commands: Record<string, string[][]>, targetRoot: string, orlyFile: string): Promise<PlannedFile[]> {
+  const registryPacks = objectValue(model.registry.packs, REGISTRY_PACKS_LABEL);
+  const known = new Set(Object.keys(registryPacks));
+  const paths = new Set(Object.values(registryPacks).flatMap((pack) => objectArray(objectValue(pack, "pack").managed_files, "managed files").map((entry) => String(entry.target))));
+  const planned = new Map<string, PlannedFile>();
+  const sources = new Map<string, string>();
+  for (const name of packs) {
+    const pack = objectValue(registryPacks[name], `pack ${name}`);
+    for (const entry of objectArray(pack.managed_files, `pack ${name} managed_files`)) {
+      if (!isString(entry.source) || !isString(entry.target)) throw new OrlyError(`pack ${name} managed file must carry string source and target`);
+      const claimed = sources.get(entry.target);
+      if (claimed && claimed !== entry.source) throw new OrlyError(`packs disagree on ${entry.target}: ${claimed} and ${entry.source}`);
+      sources.set(entry.target, entry.source);
+      const path = join(model.root, entry.source);
+      // Never overwrite the engine's pack sources with filtered consumer copies.
+      if (resolved(model.root) === resolved(targetRoot)) continue;
+      const target = installedPath(entry.target);
+      planned.set(target, { target, content: await managedContent(path, target, entry.source, packs, known, orlyFile, paths), mode: modeLabel(path) });
+      if (entry.target.includes(SKILLS_SEGMENT)) {
+        const body = await Bun.file(path).text();
+        const frontmatter = body.match(/^---\n[\s\S]*?\n---/u)?.[0] ?? "";
+        const stub = `${frontmatter}\n\nRead and follow \`${target}\` from the repository root before acting.\n`;
+        planned.set(entry.target, { target: entry.target, content: new TextEncoder().encode(stub), mode: MODE_REGULAR });
+      }
+    }
+  }
+  const rendered = await new Renderer(model).renderText(packs, commands);
+  planned.set(orlyFile, { target: orlyFile, content: new TextEncoder().encode(orlyFile === AGENTS_FILENAME ? rendered : installedReferences(rendered, paths)), mode: MODE_REGULAR });
+  return [...planned.values()].sort((left, right) => left.target.localeCompare(right.target));
+}
+
+export function resolveLayout(model: RulesModel, targetRoot: string): Layout {
+  // The engine owns its render; consumers retain their own AGENTS.md.
+  if (resolved(model.root) === resolved(targetRoot)) return { orlyFile: AGENTS_FILENAME };
+  return { orlyFile: ORLY_AGENTS_FILENAME, pointerHost: AGENTS_FILENAME };
+}
+
+function resolved(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+// Installation and verification use the same filtered bytes for each pack.
+export async function managedContent(path: string, target: string, source: string, packs: string[], known: Set<string>, orlyFile: string, paths: Set<string> = new Set()): Promise<Uint8Array> {
+  const bytes = await Bun.file(path).bytes();
+  if (extname(target) !== MARKDOWN_EXTENSION) return bytes;
+  const filtered = renderProfileText(new TextDecoder().decode(bytes), new Set(packs), known, source);
+  const retargeted = retargetRulesCitations(filtered, orlyFile);
+  return new TextEncoder().encode(`${orlyFile === AGENTS_FILENAME ? retargeted : installedReferences(retargeted, paths)}\n`);
+}
+
+// Managed rule citations must point to Orly's file, not the consumer's own rules.
+function retargetRulesCitations(text: string, orlyFile: string): string {
+  if (orlyFile === AGENTS_FILENAME) return text;
+  return text
+    .replaceAll(`](${AGENTS_FILENAME})`, `](${orlyFile})`)
+    .replaceAll(`](../${AGENTS_FILENAME})`, `](../${orlyFile})`)
+    // The relative spelling first: `../AGENTS.md` contains `AGENTS.md`, so the
+    // bare rule below would rewrite its tail and leave the `../` stranded.
+    // Missing it is what rendered `[`../AGENTS.md`](../AGENTS.orly.md)` into
+    // four managed pages — a label naming one file over a link to another.
+    .replaceAll(`\`../${AGENTS_FILENAME}\``, `\`../${orlyFile}\``)
+    .replaceAll(`\`${AGENTS_FILENAME}\``, `\`${orlyFile}\``);
+}

package/src/installation/transaction.ts

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, lstatSync } from "node:fs";
+import { dirname, join, isAbsolute } from "node:path";
+import { z } from "zod";
+import { assertWritableInside, applyMode, OrlyError, MODE_REGULAR, MODE_EXECUTABLE } from "../model";
+import { contentDigest } from "../config";
+import { hooksPath } from "./hooks";
+
+const JOURNAL = ".orly/install-journal.json";
+const MAX_JOURNAL_BYTES = 16 * 1024 * 1024;
+const JSON_INDENT = 2;
+const ENCODING = "utf8";
+const CONTENT_ENCODING = "base64";
+const OBSOLETE_FILE = "obsolete managed file";
+const JOURNAL_SIZE_ERROR = "installation journal exceeds its size budget";
+const regularPath = z.string().min(1).refine((path) => !isAbsolute(path) && !path.split(/[\\/]/).some((part) => part === ".." || !part) && !path.includes("\0"));
+const writeSchema = z.object({ path: regularPath, before: z.string().nullable(), content: z.string(), mode: z.enum([MODE_REGULAR, MODE_EXECUTABLE]) }).strict();
+const deleteSchema = z.object({ path: regularPath, before: z.string() }).strict();
+const hooksSchema = z.object({ before: z.string().nullable(), after: z.string() }).strict().nullable();
+const journalSchema = z.object({ version: z.string(), writes: z.array(writeSchema), deletes: z.array(deleteSchema), hooks: hooksSchema }).strict();
+export type FileWrite = z.infer<typeof writeSchema>;
+export type FileDelete = z.infer<typeof deleteSchema>;
+export type HooksChange = z.infer<typeof hooksSchema>;
+type Journal = z.infer<typeof journalSchema>;
+export type InstallCheckpoint = (stage: string, ordinal: number) => void;
+
+// A crash may leave either the old bytes or the intended new bytes at a path.
+// Anything else is an owner edit and must stop recovery before further writes.
+export class InstallTransaction {
+  readonly #root: string;
+  readonly #version: string;
+  readonly #checkpoint: InstallCheckpoint | undefined;
+  constructor(root: string, version: string, checkpoint?: InstallCheckpoint) {
+    this.#root = root;
+    this.#version = version;
+    this.#checkpoint = checkpoint;
+  }
+
+  recover(configureHooks: () => void): boolean {
+    assertWritableInside(this.#root, JOURNAL, "installation journal");
+    const path = join(this.#root, JOURNAL);
+    if (!existsSync(path)) return false;
+    if (lstatSync(path).size > MAX_JOURNAL_BYTES) throw new OrlyError(JOURNAL_SIZE_ERROR);
+    const envelope = z.object({ digest: z.string(), data: journalSchema }).strict().parse(JSON.parse(readFileSync(path, ENCODING)));
+    if (envelope.digest !== contentDigest(Buffer.from(JSON.stringify(envelope.data)))) throw new OrlyError("installation journal integrity mismatch");
+    if (envelope.data.version !== this.#version) throw new OrlyError("resume installation with the same package version recorded in the journal");
+    this.apply(envelope.data, configureHooks);
+    return true;
+  }
+
+  commit(writes: FileWrite[], deletes: FileDelete[], hooks: HooksChange, configureHooks: () => void): void {
+    const data = journalSchema.parse({ version: this.#version, writes, deletes, hooks });
+    this.validate(data);
+    const bytes = Buffer.from(JSON.stringify({ digest: contentDigest(Buffer.from(JSON.stringify(data))), data }, undefined, JSON_INDENT));
+    if (bytes.length > MAX_JOURNAL_BYTES) throw new OrlyError(JOURNAL_SIZE_ERROR);
+    atomicWrite(this.#root, JOURNAL, bytes, MODE_REGULAR);
+    this.#checkpoint?.("journal", 0);
+    this.apply(data, configureHooks);
+  }
+
+  private validate(data: Journal): void {
+    this.validateHooks(data.hooks);
+    const paths = [...data.writes.map((file) => file.path), ...data.deletes.map((file) => file.path)];
+    if (new Set(paths).size !== paths.length || paths.includes(JOURNAL)) throw new OrlyError("installation journal contains overlapping operations");
+    for (const file of data.writes) {
+      assertWritableInside(this.#root, file.path, "installation destination");
+      const current = diskDigest(this.#root, file.path);
+      const next = contentDigest(Buffer.from(file.content, CONTENT_ENCODING));
+      if (current !== file.before && current !== next) throw new OrlyError(`installation conflict: ${file.path} changed after planning`);
+    }
+    for (const file of data.deletes) {
+      assertWritableInside(this.#root, file.path, OBSOLETE_FILE);
+      const current = diskDigest(this.#root, file.path);
+      if (current !== null && current !== file.before) throw new OrlyError(`migration conflict: ${file.path} changed before cleanup`);
+    }
+  }
+
+  private validateHooks(hooks: HooksChange): void {
+    if (!hooks) return;
+    const current = hooksPath(this.#root);
+    if (current !== hooks.before && current !== hooks.after) throw new OrlyError("installation conflict: hooks setting changed after planning");
+  }
+
+  private apply(data: Journal, configureHooks: () => void): void {
+    this.validate(data);
+    for (const [index, file] of data.writes.entries()) {
+      const bytes = Buffer.from(file.content, CONTENT_ENCODING);
+      const current = diskDigest(this.#root, file.path);
+      if (current !== file.before && current !== contentDigest(bytes)) throw new OrlyError(`installation conflict: ${file.path}`);
+      if (current !== contentDigest(bytes)) atomicWrite(this.#root, file.path, bytes, file.mode);
+      else applyMode(join(this.#root, file.path), file.mode);
+      this.#checkpoint?.("write", index);
+    }
+    this.validateHooks(data.hooks);
+    if (data.hooks) configureHooks();
+    this.#checkpoint?.("metadata", 0);
+    for (const [index, file] of data.deletes.entries()) {
+      assertWritableInside(this.#root, file.path, OBSOLETE_FILE);
+      const current = diskDigest(this.#root, file.path);
+      if (current !== null && current !== file.before) throw new OrlyError(`migration conflict: ${file.path}`);
+      if (current !== null) unlinkSync(join(this.#root, file.path));
+      this.#checkpoint?.("delete", index);
+    }
+    unlinkSync(join(this.#root, JOURNAL));
+  }
+}
+
+export function diskDigest(root: string, path: string): string | null {
+  assertWritableInside(root, path, "installation input");
+  const file = join(root, path);
+  if (!existsSync(file)) return null;
+  if (!lstatSync(file).isFile()) throw new OrlyError(`installation requires a regular file: ${path}`);
+  return contentDigest(readFileSync(file));
+}
+
+function atomicWrite(root: string, path: string, content: Uint8Array, mode: string): void {
+  assertWritableInside(root, path, "installation write");
+  const destination = join(root, path);
+  mkdirSync(dirname(destination), { recursive: true });
+  const temporary = `${destination}.orly-pending`;
+  assertWritableInside(root, `${path}.orly-pending`, "installation temporary");
+  if (existsSync(temporary)) {
+    if (diskDigest(root, `${path}.orly-pending`) !== contentDigest(content)) throw new OrlyError(`installation temporary conflicts: ${path}.orly-pending`);
+  } else writeFileSync(temporary, content, { flag: "wx" });
+  applyMode(temporary, mode);
+  renameSync(temporary, destination);
+}

package/src/installation_preservation.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, expect, mock, spyOn, test } from "bun:test";
+import { join } from "node:path";
+import { cleanupTemporaryDirectories, newRepository, ROOT } from "./gates_test_support";
+import { install } from "./install";
+import { readConfig } from "./config";
+import { RulesModel } from "./model";
+
+afterEach(() => { mock.restore(); cleanupTemporaryDirectories(); });
+
+test("strong_assertion_exposes_real_defect", async () => {
+  const model = await RulesModel.load(ROOT);
+  const repo = newRepository();
+  const options = { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.12.0" };
+  expect((await install(model, options)).ok).toBe(true);
+  const config = await readConfig(repo);
+  const target = config!.managed.find((path) => path.endsWith("dispatch/write_any.md"))!;
+  const edited = "Owner correction that must survive an ordinary update.\n";
+  await Bun.write(join(repo, target), edited);
+  const result = await install(model, options);
+  // Existence alone passes even when the updater destroys the correction.
+  expect(await Bun.file(join(repo, target)).exists()).toBe(true);
+  expect(await Bun.file(join(repo, target)).text()).toBe(edited);
+  expect(result.ok).toBe(false);
+  expect(result.errors.some((error) => error.path === target)).toBe(true);
+});
+
+test.each([".orly/orly.json", ".orly/AGENTS.md", "AGENTS.md"])("an owner edit to %s during staging refuses without overwriting it", async (target) => {
+  const model = await RulesModel.load(ROOT);
+  const repo = newRepository();
+  const options = { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.11.0" };
+  expect((await install(model, options)).ok).toBe(true);
+  const write = Bun.write.bind(Bun);
+  const edited = "Owner edit saved while installation is staging.\n";
+  let injected = 0;
+  spyOn(Bun, "write").mockImplementation(async (destination, input, settings) => {
+    if (!injected && String(destination).includes("/install-stage-")) {
+      injected++;
+      await write(join(repo, target), edited);
+    }
+    return Reflect.apply(write, Bun, [destination, input, settings]);
+  });
+  const result = await install(model, options);
+  expect(injected).toBe(1);
+  expect(result.ok).toBe(false);
+  expect(result.errors.map((error) => error.message).join("\n")).toContain("changed after planning");
+  expect(await Bun.file(join(repo, target)).text()).toBe(edited);
+  expect(await Bun.file(join(repo, ".orly/install-journal.json")).exists()).toBe(false);
+});

package/src/judgments/advice.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+
+import { CHOICE } from "./constants";
+import { assess } from "./advice";
+import { CATALOG } from "./questions";
+import { choiceReply, noulReply, TestProject } from "./test_support";
+
+test("weak assertions receive a fixed exact-result action", async () => {
+  using project = new TestProject();
+  const result = assess(await project.prepare(), choiceReply());
+  expect(result.concern).toBe(true);
+  expect(result.uncertain).toBe(false);
+  expect(result.action).toContain("exact expected result");
+});
+
+test("insufficient and diffuse answers suggest inspection without automatic repair", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  const insufficient = assess(prepared, choiceReply(CHOICE.insufficient));
+  expect(insufficient.uncertain).toBe(true);
+  expect(insufficient.concern).toBe(false);
+  const diffuse = choiceReply();
+  const answer = diffuse.answers.decision;
+  if (answer?.type !== "choice") throw new Error("Choice fixture is invalid");
+  answer.confidence = 0.2;
+  expect(assess(prepared, diffuse).action).toContain("suggests no repair or approval");
+});
+
+test("Noul uncertainty cannot become an applicability waiver", async () => {
+  using project = new TestProject();
+  const prepared = { ...await project.prepare(), definition: CATALOG["review.rule_applicability"] };
+  const uncertain = assess(prepared, noulReply(0.5));
+  expect(uncertain.uncertain).toBe(true);
+  expect(uncertain.concern).toBe(false);
+  const applies = assess(prepared, noulReply(1));
+  expect(applies.action).toContain("owner still decides");
+  expect(assess(prepared, noulReply(0)).action).toContain("cannot suppress a finding");
+});

package/src/judgments/advice.ts

@@ -0,0 +1,32 @@
+import type { Assessment, Prepared } from "./types";
+import type { Reply } from "./wire";
+
+import { OrlyError } from "../model";
+import { ADVICE_THRESHOLD, ASSERTION_ACTIONS, CHOICE, REPLY_KEY } from "./constants";
+
+const UNCERTAIN_ACTION = "Inspect the selected context and supply any missing evidence. This uncertain answer suggests no repair or approval.";
+
+export function assess(prepared: Prepared, reply: Reply): Assessment {
+  const answer = reply.answers[REPLY_KEY];
+  if (!answer) throw new OrlyError("Validated reply has no requested answer.");
+  if (answer.type === "noul") {
+    const yes = answer.noul >= 0.5;
+    const strength = yes ? answer.noul : 1 - answer.noul;
+    const uncertain = strength < ADVICE_THRESHOLD;
+    return {
+      decision: yes ? "yes" : "no", strength, uncertain,
+      concern: !uncertain && yes === prepared.definition.yesIsConcern,
+      action: uncertain ? UNCERTAIN_ACTION : yes ? prepared.definition.yesAction : prepared.definition.noAction,
+    };
+  }
+  const probability = answer.probabilities[answer.choice];
+  const action = Object.entries(ASSERTION_ACTIONS).find(([choice]) => choice === answer.choice)?.[1];
+  if (probability === undefined || action === undefined) throw new OrlyError("Answer has no cataloged follow-up action.");
+  const strength = Math.min(answer.confidence, probability);
+  const uncertain = strength < ADVICE_THRESHOLD || answer.choice === CHOICE.insufficient;
+  return {
+    decision: answer.choice, strength, uncertain,
+    concern: !uncertain && answer.choice !== CHOICE.exact,
+    action: uncertain ? UNCERTAIN_ACTION : action,
+  };
+}