@agentsfleet/orly 0.10.14 → 0.11.0

package/src/judgments/transport.integration.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+
+import { MAX_RESPONSE_BYTES } from "./constants";
+import { choiceReply, TestProject } from "./test_support";
+import { requestAdvice } from "./transport";
+
+test("provider request crosses real HTTP with the selected request and no redirect", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  const received: string[] = [];
+  using server = Bun.serve({ port: 0, async fetch(request) {
+    received.push(await request.text());
+    expect(request.headers.get("authorization")).toBe("Bearer test-credential");
+    return Response.json(choiceReply());
+  } });
+  const reply = await requestAdvice(prepared, "test-credential", (request) => fetch(new Request(server.url, request)));
+  expect(reply).toEqual(choiceReply());
+  expect(received).toEqual([prepared.request]);
+});
+
+test("HTTP refusal never retries or echoes the response body", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  let attempts = 0;
+  using server = Bun.serve({ port: 0, fetch() { attempts++; return new Response("private-provider-detail", { status: 429 }); } });
+  const result = await requestAdvice(prepared, "test-credential", (request) => fetch(new Request(server.url, request))).catch((error: unknown) => error);
+  expect(String(result)).toContain("HTTP 429; no automatic retry");
+  expect(String(result)).not.toContain("private-provider-detail");
+  expect(attempts).toBe(1);
+});
+
+test("provider responses reject oversized and malformed JSON", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  const oversized = await requestAdvice(prepared, "unused", async () => new Response("x".repeat(MAX_RESPONSE_BYTES + 1))).catch((error: unknown) => error);
+  expect(String(oversized)).toContain("byte budget");
+  const malformed = await requestAdvice(prepared, "unused", async () => new Response("{")).catch((error: unknown) => error);
+  expect(String(malformed)).toContain("not valid JSON");
+});
+
+test("the deadline covers a stalled response body and cancels its reader", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  let canceled = false;
+  const stream = new ReadableStream<Uint8Array>({ cancel() { canceled = true; } });
+  const result = await requestAdvice(prepared, "unused", async () => new Response(stream), 1).catch((error: unknown) => error);
+  expect(String(result)).toContain("timed out and was canceled");
+  expect(canceled).toBe(true);
+  expect(stream.locked).toBe(false);
+});
+
+test("transport failure hides credentials and cancels the request", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  let observed: AbortSignal | undefined;
+  const result = await requestAdvice(prepared, "private-test-value", async (request) => {
+    observed = request.signal;
+    throw new Error("private-test-value");
+  }).catch((error: unknown) => error);
+  expect(String(result)).toContain("Provider transport failed");
+  expect(String(result)).not.toContain("private-test-value");
+  expect(observed?.aborted).toBe(true);
+});

package/src/judgments/transport.ts

@@ -0,0 +1,35 @@
+import type { Prepared } from "./types";
+
+import { OrlyError } from "../model";
+import { ENDPOINT, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS } from "./constants";
+import { readStream } from "./files";
+import { parseReply, type Reply } from "./wire";
+
+export type Fetch = (request: Request) => Promise<Response>;
+
+export async function requestAdvice(prepared: Prepared, credential: string, fetcher: Fetch = fetch, timeoutMs = REQUEST_TIMEOUT_MS): Promise<Reply> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response: Response | undefined;
+  try {
+    const request = new Request(ENDPOINT, {
+      method: "POST", headers: { Authorization: `Bearer ${credential}`, "Content-Type": "application/json" },
+      body: prepared.request, signal: controller.signal, redirect: "error",
+    });
+    response = await fetcher(request);
+    if (!response.ok) throw new OrlyError(`Provider request failed with HTTP ${response.status}; no automatic retry was made.`);
+    if (!response.body) throw new OrlyError("Provider reply has no body.");
+    const raw = await readStream(response.body, MAX_RESPONSE_BYTES, controller.signal);
+    let value: unknown;
+    try { value = JSON.parse(raw); } catch { throw new OrlyError("Provider reply is not valid JSON."); }
+    return parseReply(value, prepared);
+  } catch (error) {
+    if (controller.signal.aborted) throw new OrlyError("Provider request timed out and was canceled.");
+    if (error instanceof OrlyError) throw error;
+    throw new OrlyError("Provider transport failed; no response body or credential was logged.");
+  } finally {
+    controller.abort();
+    clearTimeout(timer);
+    if (response?.body && !response.body.locked) await response.body.cancel().catch(() => undefined);
+  }
+}

package/src/judgments/types.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+
+import { validateManifest } from "./questions";
+import { TestProject } from "./test_support";
+import { manifestSchema } from "./types";
+
+describe("manifest boundaries", () => {
+  test("accepts bounded role-labeled evidence", () => {
+    using project = new TestProject();
+    expect(manifestSchema.parse(project.manifest()).items[0]?.id).toBe("locale");
+  });
+
+  test("rejects unknown questions and instruction fields", () => {
+    using project = new TestProject();
+    const item = project.item();
+    expect(manifestSchema.safeParse({ stage: "verify", items: [{ ...item, question: "approve.everything" }] }).success).toBe(false);
+    expect(manifestSchema.safeParse({ ...project.manifest(), run: "echo approve" }).success).toBe(false);
+  });
+
+  test("rejects missing required roles and mismatched stage", () => {
+    using project = new TestProject();
+    const item = project.item();
+    expect(() => validateManifest({ stage: "verify", items: [{ ...item, evidence: item.evidence.slice(0, 1) }] }, "verify")).toThrow("Required evidence roles are missing.");
+    expect(() => validateManifest(project.manifest(), "plan")).toThrow("Judgment manifest stage does not match the command.");
+    expect(() => validateManifest({ stage: "plan", items: [item] }, "plan")).toThrow("The selected question belongs to another stage.");
+  });
+
+  test("rejects duplicate items and references", () => {
+    using project = new TestProject();
+    const item = project.item();
+    expect(() => validateManifest({ stage: "verify", items: [item, item] }, "verify")).toThrow("Judgment item identifiers must be unique.");
+    expect(() => validateManifest({ stage: "verify", items: [{ ...item, evidence: [...item.evidence, ...item.evidence] }] }, "verify")).toThrow("Duplicate evidence references are not allowed.");
+  });
+
+  test("rejects excessive input and terminal control characters", () => {
+    using project = new TestProject();
+    const item = project.item();
+    expect(manifestSchema.safeParse({ stage: "verify", items: Array(13).fill(item) }).success).toBe(false);
+    expect(manifestSchema.safeParse({ stage: "verify", items: [{ ...item, requirement: "x".repeat(2049) }] }).success).toBe(false);
+    const reference = item.evidence[0];
+    expect(manifestSchema.safeParse({ stage: "verify", items: [{ ...item, evidence: [{ ...reference, path: "label\u001b.ts" }] }] }).success).toBe(false);
+  });
+});

package/src/judgments/types.ts

@@ -0,0 +1,66 @@
+import type { Answer } from "./wire";
+
+import { z } from "zod";
+
+import { MAX_EVIDENCE, MAX_ITEMS, MAX_NAME_LENGTH, MAX_REQUIREMENT_LENGTH, QUESTIONS, ROLES, STAGES } from "./constants";
+
+const name = z.string().trim().min(1).max(MAX_NAME_LENGTH);
+const selector = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("file") }),
+  z.strictObject({ kind: z.literal("function"), name }),
+  z.strictObject({ kind: z.literal("test"), name }),
+  z.strictObject({ kind: z.literal("section"), heading: name }),
+]);
+export const referenceSchema = z.strictObject({
+  role: z.enum(ROLES),
+  path: z.string().min(1).max(512).refine((value) => !/[\x00-\x1f\x7f]/.test(value)),
+  selector,
+});
+export const itemSchema = z.strictObject({
+  id: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,47}$/),
+  question: z.enum(QUESTIONS),
+  requirement: z.string().trim().min(1).max(MAX_REQUIREMENT_LENGTH),
+  evidence: z.array(referenceSchema).min(1).max(MAX_EVIDENCE),
+});
+export const manifestSchema = z.strictObject({ stage: z.enum(STAGES), items: z.array(itemSchema).min(1).max(MAX_ITEMS) });
+
+export type Stage = z.infer<typeof manifestSchema>["stage"];
+export type Manifest = z.infer<typeof manifestSchema>;
+export type Item = z.infer<typeof itemSchema>;
+export type Reference = z.infer<typeof referenceSchema>;
+export type Selector = Reference["selector"];
+export type Role = Reference["role"];
+export type QuestionId = Item["question"];
+export type ProviderQuestion =
+  | { type: "noul"; instructions: string; criteria: { true: string; false: string } }
+  | { type: "choice"; instructions: string; criteria: Record<string, string> };
+export type Definition = {
+  stage: Stage;
+  requiredRoles: readonly Role[];
+  oneOfRoles: readonly Role[];
+  question: ProviderQuestion;
+  yesAction: string;
+  noAction: string;
+  yesIsConcern: boolean;
+};
+export type Evidence = { role: Role; path: string; selector: Selector; startLine: number; endLine: number; text: string };
+export type SourceReference = Omit<Evidence, "text"> & { digest: string };
+export type Prepared = {
+  item: Item;
+  definition: Definition;
+  identity: string;
+  request: string;
+  references: SourceReference[];
+};
+export type Assessment = { decision: string; concern: boolean; uncertain: boolean; strength: number; action: string };
+export type CompletedItem = {
+  status: "complete"; id: string; question: QuestionId; mode: "live" | "replay";
+  model: string; identity: string; sources: SourceReference[]; assessment: Assessment;
+  answer: Answer; requests: number; elapsedMs: number; usage: { input_tokens: number; output_tokens: number };
+};
+export type IncompleteItem = {
+  status: "incomplete"; id: string; question: QuestionId; reason: string;
+  requests: number; elapsedMs: number; usage: { input_tokens: number; output_tokens: number } | null;
+};
+export type ItemResult = CompletedItem | IncompleteItem;
+export type Report = { stage: Stage; advisory: true; requests: number; results: ItemResult[] };

package/src/judgments/wire.test.ts

@@ -0,0 +1,48 @@
+import { expect, test } from "bun:test";
+
+import { CHOICE, REPLY_KEY } from "./constants";
+import { CATALOG } from "./questions";
+import { choiceReply, noulReply, TestProject } from "./test_support";
+import { parseReply } from "./wire";
+
+test("validates the requested choice distribution and pinned model", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  expect(parseReply(choiceReply(), prepared).answers[REPLY_KEY]).toEqual(choiceReply().answers[REPLY_KEY]);
+});
+
+test("rejects invalid schema, model and answer type", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  expect(() => parseReply({ ...choiceReply(), model: "jev-latest" }, prepared)).toThrow("Provider reply does not match the pinned model and answer schema.");
+  expect(() => parseReply(noulReply(1), prepared)).toThrow("Provider answer has the wrong question type.");
+  expect(() => parseReply({ ...choiceReply(), usage: { input_tokens: -1, output_tokens: 0 } }, prepared)).toThrow("Provider reply does not match the pinned model and answer schema.");
+});
+
+test("rejects missing answers and extra answers", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  const reply = choiceReply();
+  expect(() => parseReply({ ...reply, answers: {} }, prepared)).toThrow("Provider reply must answer the requested question exactly once.");
+  expect(() => parseReply({ ...reply, answers: { ...reply.answers, extra: reply.answers[REPLY_KEY] } }, prepared)).toThrow("Provider reply must answer the requested question exactly once.");
+});
+
+test("rejects omitted options, bad sums and a non-maximum choice", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  const reply = choiceReply();
+  const answer = reply.answers[REPLY_KEY];
+  if (answer?.type !== "choice") throw new Error("Choice fixture is invalid");
+  const replace = (probabilities: Record<string, number>, choice: string = CHOICE.weak) => ({ ...reply, answers: { [REPLY_KEY]: { ...answer, probabilities, choice } } });
+  expect(() => parseReply(replace({ [CHOICE.weak]: 1 }), prepared)).toThrow("Provider probabilities do not match the requested choices.");
+  expect(() => parseReply(replace({ ...answer.probabilities, [CHOICE.exact]: 0.2 }), prepared)).toThrow("Provider probabilities do not sum to one.");
+  expect(() => parseReply(replace(answer.probabilities, CHOICE.exact), prepared)).toThrow("Provider choice is not a highest-probability option.");
+});
+
+test("rejects non-finite and out-of-range probabilities", async () => {
+  using project = new TestProject();
+  const prepared = await project.prepare();
+  for (const number of [NaN, Infinity, -0.1, 1.1]) {
+    expect(() => parseReply(noulReply(number), { ...prepared, definition: CATALOG["plan.prerequisites"] })).toThrow("Provider reply does not match the pinned model and answer schema.");
+  }
+});

package/src/judgments/wire.ts

@@ -0,0 +1,40 @@
+import type { Prepared, ProviderQuestion } from "./types";
+
+import { z } from "zod";
+
+import { OrlyError } from "../model";
+import { ANSWER_KIND, MODEL, PROBABILITY_TOLERANCE, REPLY_KEY } from "./constants";
+
+const probability = z.number().finite().min(0).max(1);
+const answerSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal(ANSWER_KIND.noul), noul: probability }),
+  z.strictObject({ type: z.literal(ANSWER_KIND.choice), choice: z.string(), probabilities: z.record(z.string(), probability), confidence: probability }),
+]);
+export const usageSchema = z.strictObject({ input_tokens: z.number().int().nonnegative(), output_tokens: z.number().int().nonnegative() });
+export const replySchema = z.object({ model: z.literal(MODEL), answers: z.record(z.string(), answerSchema), usage: usageSchema });
+export type Reply = z.infer<typeof replySchema>;
+export type Answer = z.infer<typeof answerSchema>;
+
+export function parseReply(value: unknown, prepared: Prepared): Reply {
+  const parsed = replySchema.safeParse(value);
+  if (!parsed.success) throw new OrlyError("Provider reply does not match the pinned model and answer schema.");
+  const reply = parsed.data;
+  const keys = Object.keys(reply.answers);
+  const answer = reply.answers[REPLY_KEY];
+  if (keys.length !== 1 || !answer) throw new OrlyError("Provider reply must answer the requested question exactly once.");
+  validateAnswer(answer, prepared.definition.question);
+  return reply;
+}
+
+function validateAnswer(answer: Answer, question: ProviderQuestion): void {
+  if (answer.type !== question.type) throw new OrlyError("Provider answer has the wrong question type.");
+  if (answer.type !== ANSWER_KIND.choice || question.type !== ANSWER_KIND.choice) return;
+  const expected = Object.keys(question.criteria).sort();
+  const actual = Object.keys(answer.probabilities).sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new OrlyError("Provider probabilities do not match the requested choices.");
+  const probabilities = Object.values(answer.probabilities);
+  const sum = probabilities.reduce((total, value) => total + value, 0);
+  if (Math.abs(sum - 1) > PROBABILITY_TOLERANCE) throw new OrlyError("Provider probabilities do not sum to one.");
+  const selected = answer.probabilities[answer.choice];
+  if (selected === undefined || selected + PROBABILITY_TOLERANCE < Math.max(...probabilities)) throw new OrlyError("Provider choice is not a highest-probability option.");
+}

package/src/loaders.test.ts

@@ -32,7 +32,7 @@ describe("runtime loaders", () => {
     // and passes through the repository's own file on the way to orly's.
     expect(await Bun.file(join(repo, "CLAUDE.md")).text()).toContain("\n@AGENTS.md\n");
     expect(JSON.parse(await Bun.file(join(repo, "opencode.json")).text()).instructions)
-      .toEqual(["AGENTS.md", "AGENTS.orly.md"]);
+      .toEqual(["AGENTS.md", ".orly/AGENTS.md"]);
   });
 
   // The line that does the work. Backticked it is decoration, which is what the
@@ -44,8 +44,8 @@ describe("runtime loaders", () => {
     await installInto(repo);
 
     const host = await Bun.file(join(repo, "AGENTS.md")).text();
-    expect(host).toContain("\n@AGENTS.orly.md\n");
-    expect(host).not.toContain("`@AGENTS.orly.md`");
+    expect(host).toContain("\n@.orly/AGENTS.md\n");
+    expect(host).not.toContain("`@.orly/AGENTS.md`");
   });
 
   test("loaders are idempotent — a second install writes nothing", async () => {
@@ -87,22 +87,19 @@ describe("runtime loaders", () => {
     expect(host).toContain("keep me");
     expect(host).toContain("trailing prose");
     expect(host).not.toContain("stale pointer");
-    expect(host).toContain("\n@AGENTS.orly.md\n");
+    expect(host).toContain("\n@.orly/AGENTS.md\n");
   });
 
-  // The migration path for every repository installed before the loaders
-  // existed, and for every later change to the loader's own wording: the
-  // banner is the authorship evidence, so orly's own file is orly's to refresh.
-  test("a CLAUDE.md orly wrote itself is refreshed, not left stale", async () => {
+  test("an unrecorded Claude banner cannot authorize deleting existing instructions", async () => {
     const repo = newRepository();
-    await Bun.write(join(repo, "CLAUDE.md"), "> **Generated by `orly`.**\n> an older loader\n\n@ELSEWHERE.md\n");
+    const ownerContent = "> **Generated by `orly`.**\n> an older loader\n\n@ELSEWHERE.md\n";
+    await Bun.write(join(repo, "CLAUDE.md"), ownerContent);
 
     const result = await installInto(repo);
 
-    expect(result.written).toContain("CLAUDE.md");
+    expect(result.written).not.toContain("CLAUDE.md");
     const loader = await Bun.file(join(repo, "CLAUDE.md")).text();
-    expect(loader).toContain("\n@AGENTS.md\n");
-    expect(loader).not.toContain("ELSEWHERE");
+    expect(loader).toBe(ownerContent);
   });
 
   // A link orly cannot resolve is still someone's deliberate wiring. Writing
@@ -114,9 +111,9 @@ describe("runtime loaders", () => {
 
     const result = await installInto(repo);
 
-    expect(result.ok).toBe(true);
+    expect(result.ok).toBe(false);
     expect(result.written).not.toContain("CLAUDE.md");
-    expect(result.skipped).toContain("CLAUDE.md");
+    expect(result.errors.some((error) => error.message.includes("unresolved symbolic link"))).toBe(true);
     expect(existsSync(join(repo, "nowhere.md"))).toBe(false);
     expect(lstatSync(join(repo, "CLAUDE.md")).isSymbolicLink()).toBe(true);
   });
@@ -159,7 +156,7 @@ describe("runtime loaders", () => {
 
     const config = JSON.parse(await Bun.file(join(repo, "opencode.json")).text());
     expect(config.model).toBe("anthropic/claude-fable-5");
-    expect(config.instructions).toEqual(["AGENTS.md", "AGENTS.orly.md"]);
+    expect(config.instructions).toEqual(["AGENTS.md", ".orly/AGENTS.md"]);
     expect(result.written).toContain("opencode.json");
   });
 
@@ -191,6 +188,6 @@ describe("runtime loaders", () => {
     expect(result.ok).toBe(false);
     expect(result.errors.some((error) => error.path === "opencode.json")).toBeTrue();
     expect(await Bun.file(victim).text()).toBe("not orly's to write\n");
-    expect(existsSync(join(repo, "AGENTS.orly.md"))).toBe(false);
+    expect(existsSync(join(repo, ".orly/AGENTS.md"))).toBe(false);
   });
 });

package/src/loaders.ts

@@ -18,7 +18,7 @@ import { assertWritableInside, isObject } from "./model";
 // once someone else has written one.
 
 export const AGENTS_FILENAME = "AGENTS.md";
-export const ORLY_AGENTS_FILENAME = "AGENTS.orly.md";
+export const ORLY_AGENTS_FILENAME = ".orly/AGENTS.md";
 export const GENERATED_BANNER = "> **Generated by `orly`.**";
 export const POINTER_HOST_KIND = "pointer host";
 
@@ -31,6 +31,7 @@ const POINTER_OPEN = "<!-- orly:begin -->";
 const POINTER_CLOSE = "<!-- orly:end -->";
 const NEWLINE = "\n";
 const JSON_INDENT = 2;
+const PREVIOUS_AGENTS_FILENAME = "AGENTS.orly.md";
 
 export type Layout = { orlyFile: string; pointerHost?: string };
 export type LoaderResult = { written: string[]; skipped: string[] };
@@ -56,7 +57,7 @@ export function loaderTargets(layout: Layout): Array<[string, string]> {
 // Run after the managed files land, so a repository whose install refused for
 // any other reason never carries a loader pointing at rules that were not
 // written.
-export async function installLoaders(targetRoot: string, layout: Layout): Promise<LoaderResult> {
+export async function installLoaders(targetRoot: string, layout: Layout, obsolete: readonly string[] = []): Promise<LoaderResult> {
   const written: string[] = [];
   const skipped: string[] = [];
   const record = (path: string, verdict: Verdict) => (verdict === WRITTEN ? written : skipped).push(path);
@@ -68,7 +69,7 @@ export async function installLoaders(targetRoot: string, layout: Layout): Promis
   const host = layout.pointerHost ?? layout.orlyFile;
   if (layout.pointerHost) record(layout.pointerHost, await upsertPointer(targetRoot, layout.pointerHost, layout.orlyFile));
   record(CLAUDE_FILENAME, await upsertClaudeLoader(targetRoot, host));
-  record(OPENCODE_FILENAME, await upsertOpencodeLoader(targetRoot, [...new Set([host, layout.orlyFile])]));
+  record(OPENCODE_FILENAME, await upsertOpencodeLoader(targetRoot, [...new Set([host, layout.orlyFile])], obsolete));
   return { written, skipped };
 }
 
@@ -121,7 +122,7 @@ async function upsertPointer(targetRoot: string, host: string, orlyFile: string)
   // No file, or one orly generated under an older layout where it owned this
   // name. Neither holds a line the repository wrote, so both become the stub —
   // which is the migration for anything installed before the split.
-  if (!existsSync(path) || (await Bun.file(path).text()).startsWith(GENERATED_BANNER)) {
+  if (!existsSync(path)) {
     await Bun.write(path, `${stubHost(block)}\n`);
     return WRITTEN;
   }
@@ -161,14 +162,28 @@ async function upsertClaudeLoader(targetRoot: string, host: string): Promise<Ver
   }
   const current = await Bun.file(path).text();
   if (current === content) return CURRENT;
-  // An older loader of orly's own making is orly's to refresh; anything else
-  // is the repository's file and is reported, not edited.
-  if (!current.startsWith(GENERATED_BANNER)) return THEIRS;
+  const start = current.indexOf(POINTER_OPEN);
+  const end = current.indexOf(POINTER_CLOSE);
+  if (start >= 0 && end > start) {
+    const updated = `${current.slice(0, start)}${claudeBlock(host)}${current.slice(end + POINTER_CLOSE.length)}`;
+    if (updated === current) return CURRENT;
+    await Bun.write(path, updated);
+    return WRITTEN;
+  }
+  if (current !== previousClaudeLoader(host) && current !== previousClaudeLoader(PREVIOUS_AGENTS_FILENAME)) return THEIRS;
   await Bun.write(path, content);
   return WRITTEN;
 }
 
 function claudeLoader(host: string): string {
+  return [GENERATED_BANNER, claudeBlock(host), ""].join(NEWLINE);
+}
+
+function claudeBlock(host: string): string {
+  return [POINTER_OPEN, `@${host}`, POINTER_CLOSE].join(NEWLINE);
+}
+
+function previousClaudeLoader(host: string): string {
   return [
     GENERATED_BANNER,
     "> Claude Code loads this file at session start and no other, so this is where",
@@ -214,7 +229,7 @@ function linkVerdict(targetRoot: string, path: string, host: string): Verdict |
 // An existing config is edited by adding what is missing and nothing else. A
 // config orly cannot parse is left exactly as it is: rewriting a file whose
 // shape we do not understand is how an install eats someone's settings.
-async function upsertOpencodeLoader(targetRoot: string, entries: string[]): Promise<Verdict> {
+async function upsertOpencodeLoader(targetRoot: string, entries: string[], obsolete: readonly string[]): Promise<Verdict> {
   assertWritableInside(targetRoot, OPENCODE_FILENAME, LOADER_KIND);
   const path = join(targetRoot, OPENCODE_FILENAME);
   if (!existsSync(path)) {
@@ -228,9 +243,12 @@ async function upsertOpencodeLoader(targetRoot: string, entries: string[]): Prom
     return THEIRS;
   }
   if (!isObject(config)) return THEIRS;
-  const listed = Array.isArray(config[INSTRUCTIONS_KEY]) ? config[INSTRUCTIONS_KEY].map(String) : [];
+  const instructions = config[INSTRUCTIONS_KEY];
+  if (instructions !== undefined && (!Array.isArray(instructions) || instructions.some((entry) => typeof entry !== "string"))) return THEIRS;
+  const original: string[] = Array.isArray(instructions) ? instructions : [];
+  const listed = original.filter((entry) => !obsolete.includes(entry));
   const missing = entries.filter((entry) => !listed.includes(entry));
-  if (missing.length === 0) return CURRENT;
+  if (missing.length === 0 && listed.length === original.length) return CURRENT;
   await Bun.write(path, serialise({ ...config, [INSTRUCTIONS_KEY]: [...listed, ...missing] }));
   return WRITTEN;
 }

package/src/model.test.ts

@@ -1,9 +1,26 @@
-import { describe, expect, test } from "bun:test";
-import { resolve } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, symlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
 
-import { readJsonObject, RulesModel } from "./model";
+import { assertWritableInside, readJsonObject, RulesModel } from "./model";
+import { cleanupTemporaryDirectories, temporaryDirectory } from "./gates_test_support";
 
 const ROOT = resolve(import.meta.dir, "..");
+const FIRST_LINK = "first-link";
+const SECOND_LINK = "second-link";
+const MISSING = "missing-destination";
+
+afterEach(cleanupTemporaryDirectories);
+
+test("a dangling multi-link destination refuses before creating outside content", () => {
+  const root = temporaryDirectory();
+  const outside = temporaryDirectory();
+  symlinkSync(join(outside, MISSING), join(root, SECOND_LINK));
+  symlinkSync(SECOND_LINK, join(root, FIRST_LINK));
+  expect(() => assertWritableInside(root, FIRST_LINK, "probe")).toThrow("unresolved symbolic link");
+  expect(() => assertWritableInside(root, `${FIRST_LINK}/child`, "probe")).toThrow("unresolved symbolic link");
+  expect(existsSync(join(outside, MISSING))).toBe(false);
+});
 
 describe("RulesModel", () => {
   test("validates the current registry", async () => {

package/src/model.ts

@@ -1,4 +1,4 @@
-import { chmodSync, existsSync, lstatSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import { validateActiveRule, validateRelativePath } from "./validation";
@@ -7,8 +7,8 @@ export type JsonObject = Record<string, unknown>;
 
 const HASH_ALGORITHM = "sha256";
 const HASH_ENCODING = "hex";
-const MODE_EXECUTABLE = "0755";
-const MODE_REGULAR = "0644";
+export const MODE_EXECUTABLE = "0755";
+export const MODE_REGULAR = "0644";
 const EXECUTABLE_BITS = 0o755;
 const OCTAL = 8;
 
@@ -41,6 +41,7 @@ export function isBelow(path: string, root: string): boolean {
 export function nearestExistingAncestor(path: string): string {
   let current = path;
   while (!existsSync(current)) {
+    if (isSymbolicLink(current)) safeRealpath(current);
     const parent = dirname(current);
     if (parent === current) return current;
     current = parent;
@@ -81,23 +82,12 @@ function isSymbolicLink(path: string): boolean {
   }
 }
 
-// A dangling link resolves nowhere; judge it by where it points, not where it
-// lands, so a link to a not-yet-created file outside the repository still fails.
-//
-// The directory holding it is resolved too, and has to be: the caller compares
-// this against a realpath'd root, and a lexical answer put a link pointing
-// squarely INSIDE the repository on the wrong side of that comparison wherever
-// the repository itself sits behind a symlink — which is every macOS temporary
-// directory, and plenty of real checkouts. The refusal even named the file it
-// was about to protect, one path component at a time.
-//
-// Resolving the parent cannot fail here: this runs only where the destination
-// itself lstat'd as a link, which a missing parent makes impossible.
-function safeRealpath(path: string): string | undefined {
+// Unresolved links cannot prove containment, including chains with missing parents.
+function safeRealpath(path: string): string {
   try {
     return realpathSync(path);
   } catch {
-    return resolve(realpathSync(dirname(path)), readlinkSync(path));
+    throw new OrlyError(`refusing unresolved symbolic link: ${path}`);
   }
 }
 
@@ -252,4 +242,3 @@ export function normalizedMode(path: string): number {
 export function setNormalizedMode(path: string, source: string): void {
   chmodSync(path, normalizedMode(source));
 }
-

package/src/pack_hygiene.test.ts

@@ -8,8 +8,48 @@ import { PRODUCT_ONLY_TARGETS, productLeakErrors, shippedFiles } from "./pack_hy
 const registryFor = (pack: string, source: string) => ({
   packs: { [pack]: { documents: [{ source, target: source }] } },
 });
+const GUIDE_PATH = "docs/GUIDE.md";
+const PRODUCT_COMMAND = "Run `make test-integration` before you ship.";
 
 describe("productLeakErrors", () => {
+  test("checks string core documents and retains source lines after product blocks", async () => {
+    const output = mkdtempSync(join(tmpdir(), "orly-core-hygiene-"));
+    try {
+      mkdirSync(join(output, "docs"));
+      await Bun.write(join(output, GUIDE_PATH), [
+        "<!-- oracle-packs:start product.agentsfleet -->",
+        PRODUCT_COMMAND,
+        "<!-- oracle-packs:end -->",
+        PRODUCT_COMMAND,
+      ].join("\n"));
+      const errors = await productLeakErrors(output, {
+        core_documents: [GUIDE_PATH],
+        packs: { "product.agentsfleet": {} },
+      });
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain(`${GUIDE_PATH}:4`);
+    } finally {
+      rmSync(output, { recursive: true, force: true });
+    }
+  });
+
+  test("allows a product-only command when the installer excludes its block", async () => {
+    const output = mkdtempSync(join(tmpdir(), "orly-profile-hygiene-"));
+    try {
+      mkdirSync(join(output, "docs"));
+      await Bun.write(join(output, GUIDE_PATH), [
+        "<!-- oracle-packs:start product.agentsfleet -->",
+        PRODUCT_COMMAND,
+        "<!-- oracle-packs:end -->",
+        "Use the repository's declared integration command.",
+      ].join("\n"));
+      const registry = registryFor("domain.http", GUIDE_PATH);
+      Object.assign(registry.packs, { "product.agentsfleet": {} });
+      expect(await productLeakErrors(output, registry)).toEqual([]);
+    } finally {
+      rmSync(output, { recursive: true, force: true });
+    }
+  });
   test("flags a product-only target named by a generic pack", async () => {
     const output = mkdtempSync(join(tmpdir(), "orly-hygiene-"));
     try {
@@ -81,12 +121,13 @@ describe("shippedFiles", () => {
         "domain.http": { documents: [{ source: "docs/A.md" }] },
         "product.agentsfleet": { documents: [{ source: "docs/B.md" }] },
       },
-      core_documents: [{ source: "docs/C.md" }],
+      core_documents: [{ source: "docs/C.md" }, "docs/D.md"],
     });
 
     expect(files).toContainEqual({ source: "docs/A.md", pack: "domain.http" });
     expect(files).toContainEqual({ source: "docs/B.md", pack: "product.agentsfleet" });
     expect(files).toContainEqual({ source: "docs/C.md", pack: "core" });
+    expect(files).toContainEqual({ source: "docs/D.md", pack: "core" });
   });
 });