@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/init.mjs

@@ -5,21 +5,29 @@
 // Exit 0 wrote · 2 refused, declined or could not run; never 1, since it renders no verdict on a workspace.
 
 import fs from "node:fs";
+import { assertNoSourceJournal } from "./instructions-journal.mjs";
 import path from "node:path";
+import { isInside } from "./inside.mjs";
+import { outsideTempParents, previewAlways } from "./init-preview.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 import { historyCount } from "./comments.mjs";
-import { CACHE_LIFETIMES, compileGuidance } from "./compile.mjs";
-import { alwaysTier, ESTIMATED_BYTES_PER_TOKEN, OFFER_FLOOR_TOKENS, tokensOf } from "./context.mjs";
-import { cardIgnored, changesReadme, claudeRulesUnignore, commentsRecipe, commentsRecipeEntry, COMPILED_CARD, draftCard, handoffIndexIgnore, handoffsReadme, withIgnoreLines } from "./form.mjs";
+import { CACHE_LIFETIMES, compileGuidance, readOwnedText, readOwnedBytes } from "./compile.mjs";
+import { alwaysTier, declaredContext, ESTIMATED_BYTES_PER_TOKEN, OFFER_FLOOR_TOKENS, tokensOf } from "./context.mjs";
+import { cardIgnored, gitIn, changesReadme, claudeRulesUnignore, commentsRecipe, commentsRecipeEntry, COMPILED_CARD, draftCard, handoffIndexIgnore, handoffsReadme, withIgnoreLines } from "./form.mjs";
 import { offerText, splitOffers } from "./instructions.mjs";
 import { offerLines } from "./sessions.mjs";
+import { HANDOFF_OFFER, handoffOffer } from "./handoff-policy.mjs";
+import { eligibleHandoffDate, handoffEntries, renderHandoffIndex } from "./index.mjs";
+import { readSpend } from "./ledger.mjs";
+import { spendOffer, spendOfferLines } from "./spend-offer.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 /** A refusal, thrown only before the first write: `run` exits 2 on it. */
 export class InitError extends Error {}
+class CutoffError extends InitError {}
 
 // The schema's `$defs/slug`; unreadable, it is null for `run` to refuse, since a throw at import leaves only a stack trace.
 let SCHEMA_ERROR = null;
@@ -48,7 +56,7 @@ const RESIDENCES = new Set(["in-repo", "pointer"]);
 
 const DEFAULT_CHECKPOINTS = "rituals/checkpoints";
 
-const ANSWER_KEYS = new Set(["residence", "name", "summary", "governed-by", "feed", "checkpoints", "cycle", "pack-root", "cache-lifetime"]);
+const ANSWER_KEYS = new Set(["residence", "name", "summary", "governed-by", "feed", "checkpoints", "cycle", "pack-root", "cache-lifetime", "multipliers", "horizon", "handoff-budget"]);
 
 /** `text` as a slug, or null where nothing survives: `init` asks rather than name a workspace nobody chose. */
 export function slugify(text) {
@@ -66,7 +74,7 @@ export function parseArgs(argv) {
     const targets = [];
     let help = false;
 
-    const VALUED = new Set(["--residence", "--name", "--summary", "--governed-by", "--feed", "--checkpoints", "--answers", "--pack-root", "--cache-lifetime"]);
+    const VALUED = new Set(["--residence", "--name", "--summary", "--governed-by", "--feed", "--checkpoints", "--answers", "--pack-root", "--cache-lifetime", "--multipliers", "--horizon", "--handoff-budget"]);
 
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -177,6 +185,9 @@ export function resolveAnswers(flags) {
         // An answers file may give a string, the repeatable flag an array.
         packRoots: [merged["pack-root"] ?? []].flat(),
         cacheLifetime: merged["cache-lifetime"] ?? null,
+        handoffBudget: merged["handoff-budget"] ?? null,
+        multipliers: merged.multipliers ?? null,
+        horizon: merged.horizon ?? null,
     };
 }
 
@@ -205,15 +216,17 @@ export function validateAnswers(answers) {
     }
     const misplaced = {
         "in-repo": ["feed", "governed-by"],
-        pointer: ["pack-root", "checkpoints", "cycle", "cache-lifetime"],
+        pointer: ["pack-root", "checkpoints", "cycle", "cache-lifetime", "multipliers", "horizon", "handoff-budget"],
     }[answers.residence].filter((key) => answers.given.has(key));
     if (misplaced.length) {
         const spelling = (key) => (key === "cycle" ? "`--no-cycle`" : `\`--${key}\``);
         const why =
             answers.residence === "pointer"
                 ? [
-                      misplaced.some((key) => key !== "cache-lifetime") && "a pointer holds no policy of its own, so it composes no packs",
+                      misplaced.some((key) => ["pack-root", "checkpoints", "cycle"].includes(key)) && "a pointer holds no policy of its own, so it composes no packs",
                       misplaced.includes("cache-lifetime") && "a pointer drafts no repository whose settings `compile` writes, so a cache lifetime would reach no session",
+                      misplaced.includes("handoff-budget") && "a pointer holds no handoff policy of its own",
+                      misplaced.some((key) => ["multipliers", "horizon"].includes(key)) && "a pointer holds no spend policy of its own",
                   ].filter(Boolean)
                 : ["a workspace that lives here has no governor and no feed to be delivered from"];
         throw new InitError(
@@ -223,6 +236,18 @@ export function validateAnswers(answers) {
         );
     }
     const lifetime = answers.cacheLifetime ?? null;
+    try {
+        const handoff = handoffOffer(answers.handoffBudget);
+        if (handoff && !SLUG.test(handoff.context.ratio.calibrated_by)) throw new InitError("the calibration reference must be a slug");
+    }
+    catch (error) { throw new InitError(error.message); }
+    if (answers.alwaysBudget) {
+        declaredContext({ context: { ratio: answers.alwaysBudget.ratio, always: { budget: { tokens: answers.alwaysBudget.tokens } } } });
+        if (!SLUG.test(answers.alwaysBudget.ratio.calibrated_by)) throw new InitError("the calibration reference must be a slug");
+        const shared = handoffOffer(answers.handoffBudget)?.context.ratio;
+        if (shared && (shared.bytes_per_token !== answers.alwaysBudget.ratio.bytes_per_token || shared.calibrated_by !== answers.alwaysBudget.ratio.calibrated_by)) throw new InitError("always and handoff budgets must share one ratio");
+    }
+    answers.spend = spendAnswers(answers);
     if (lifetime !== null && !CACHE_LIFETIMES.includes(lifetime)) {
         throw new InitError(
             `\`${lifetime}\` is not a cache lifetime — Claude Code takes ${CACHE_LIFETIMES.map((v) => `\`${v}\``).join(" and ")}, ` +
@@ -258,15 +283,36 @@ export function validateAnswers(answers) {
     }
 }
 
+function spendAnswers(answers) {
+    const spend = {};
+    try {
+        if (answers.multipliers != null) spend.multipliers = JSON.parse(answers.multipliers);
+        if (answers.horizon != null) {
+            if (!/^[1-9]\d*$/.test(answers.horizon) || !Number.isSafeInteger(Number(answers.horizon))) throw new Error("--horizon needs a positive safe integer in decimal requests");
+            spend.horizon = { requests: Number(answers.horizon) };
+        }
+        readSpend(spend, "init answers");
+    } catch (error) { throw new InitError(`invalid spend declaration — ${error.message}`); }
+    return Object.keys(spend).length ? spend : null;
+}
+
 // ------------------------------------------------------------------------- the codebase scan
 
 /** What the repository says of itself, observed only: a field nothing states stays null, never a likely default. */
-export function scan(dir, { comments = true } = {}) {
+export function scan(dir, { comments = true, env } = {}) {
     const observed = { stack: [], build: null, test: null, run: null, name: null, vcs: null, evidence: [], commentHistory: null, uncounted: null };
-    const has = (rel) => fs.existsSync(path.join(dir, rel));
+    const owner = fs.realpathSync(dir);
+    const has = rel => {
+        try {
+            const real = fs.realpathSync(path.join(dir, rel));
+            if (!isInside(owner, real)) return false;
+            const value = fs.statSync(real);
+            return value.isFile() || rel === ".git" && value.isDirectory();
+        } catch { return false; }
+    };
     const read = (rel) => {
         try {
-            return fs.readFileSync(path.join(dir, rel), "utf8");
+            return has(rel) ? readOwnedText(path.join(dir, rel), owner) : null;
         } catch {
             return null;
         }
@@ -313,7 +359,7 @@ export function scan(dir, { comments = true } = {}) {
 
     if (comments) {
         try {
-            observed.commentHistory = historyCount(dir);
+            observed.commentHistory = historyCount(dir, { timeout: 1000, env, noFsmonitor: true });
         } catch (error) {
             observed.uncounted = error.message;
         }
@@ -398,9 +444,10 @@ function draftWorkspace(answers, observed) {
     const files = new Map();
     const name = answers.name ?? "workspace";
     const lifetime = answers.cacheLifetime ?? null;
+    const offeredHandoffs = handoffOffer(answers.handoffBudget, { newest: answers.handoffNewest, today: answers.handoffToday });
 
     const manifest = {
-        portulan: { spec: lifetime === null ? WORKSPACE_SPEC : SESSIONS_SPEC },
+        portulan: { spec: offeredHandoffs ? "2.15" : answers.spend ? "2.12" : lifetime === null ? WORKSPACE_SPEC : SESSIONS_SPEC },
         name,
         summary: answers.summary ?? `The ${name} workspace — drafted by \`init\`, and not yet curated.`,
         kind: "repository",
@@ -438,6 +485,12 @@ function draftWorkspace(answers, observed) {
     };
     if (answers.cycle) manifest.packs = [answers.checkpoints];
     if (lifetime !== null) manifest.sessions = { cache_lifetime: lifetime };
+    if (offeredHandoffs) {
+        Object.assign(manifest, offeredHandoffs);
+        renderHandoffIndex(manifest, { records: [], bytes: 0 });
+    }
+    if (answers.alwaysBudget) manifest.context = { ratio: answers.alwaysBudget.ratio, always: { budget: { tokens: answers.alwaysBudget.tokens } } };
+    if (answers.spend) manifest.spend = answers.spend;
     const commented = observed.commentHistory !== null;
 
     files.set(".portulan/workspace.json", { contents: json(manifest) });
@@ -754,7 +807,7 @@ is a command in a file.
 | Recipe | What it checks |
 |---|---|
 | \`workspace\` | **Nothing yet — it exits 2.** Replace it with the command that tells you this repository is healthy. This one is the **default**: it is what runs at a session end. |
-| \`index\` | The handoff series renders an index line for every handoff, and a copy of the index kept on disk matches it byte for byte; none is kept as drafted. Finished as drafted — it checks a real thing today. |${commented ? `
+| \`index\` | Handoff dates and declared caps are checked; the index renders its declared window, and a kept copy matches byte for byte; none is kept as drafted. Finished as drafted — it checks a real thing today. |${commented ? `
 | \`comments\` | No more comment lines record a change's history than its \`LIMIT\`, the count \`init\` found. Lower it as they leave. It needs git, and finds the CLI as \`index\` does, but takes a \`portulan\` on \`PATH\` only where it holds \`comments.mjs\`. |` : ""}
 
 ## The three exit codes, and why the middle one is not enough
@@ -776,7 +829,7 @@ where \`node\` itself is absent, the recipe exits **2** and names what it looked
 to expect on CI until the CLI is installed there; it is not a red, and it is not a pass either.
 
 **Repairing is yours, and the rail deliberately does not do it.** A check that repaired what it found
-would report green on a repository nobody had corrected. A handoff that yields no index line needs its
+would report green on a repository nobody had corrected. An invalid handoff date or required heading needs its
 title or date fixed; a kept copy that drifted needs the index tool run again, or the copy deleted.
 
 **One thing the three locations cannot establish, said rather than left implicit.** The second of them
@@ -818,12 +871,11 @@ function draftIndexRecipe() {
     return `#!/usr/bin/env bash
 # Records rail — the handoff series is rendered as its index, in memory.
 #
-# The index is not kept: \`index --handoffs\` prints it. This recipe renders it, so a handoff that yields
-# no index line is a RED, and a copy someone keeps on disk is compared byte for byte, so one edited by
-# hand or left behind when a handoff was added is a RED too. Nothing here writes.
+# \`index --handoffs\` prints on demand. Checks dates, caps and the full window.
+# Kept copies are byte-compared; omitted entries keep their source handoffs.
 #
-#   exit 0   green: every handoff yields a line, and any kept copy matches
-#   exit 1   red: one does not — fix the handoff, or regenerate or delete the copy
+#   exit 0   green: dates, caps and window hold; any kept copy matches
+#   exit 1   red: repair the handoff, or regenerate or delete a stale copy
 #   exit 2   could not run: the Portulan CLI is not reachable from here. NEVER a pass.
 
 set -uo pipefail
@@ -884,7 +936,7 @@ exit "\$code"
 }
 
 /** After the write, so a failed compile only warns; the guidance half only, since `.claude/settings.json` comes from a `compile` a person runs. */
-function reportCard(target, say, warn) {
+function reportCard(target, say, warn, interviewing = false, env) {
     try {
         compileGuidance(target);
         say(`init: compiled the boot card into ${COMPILED_CARD}, which Claude Code loads into every context here`);
@@ -892,7 +944,7 @@ function reportCard(target, say, warn) {
         warn(`init: the boot card was drafted and NOT compiled — ${error.message}. Until \`portulan compile\` runs clean, a session here boots through the slots, as before`);
         return;
     }
-    if (cardIgnored(target)) {
+    if (cardIgnored(target, gitIn(target, { env, timeout: 1000, noFsmonitor: true }))) {
         warn(`init: git ignores ${COMPILED_CARD}, so the card would reach no review and no fresh checkout — add an exception for it to .gitignore`);
     }
     let bytes;
@@ -903,16 +955,15 @@ function reportCard(target, say, warn) {
         return;
     }
     const tokens = tokensOf(bytes, ESTIMATED_BYTES_PER_TOKEN);
-    say(
-        `init: the always tier here is ~${tokens.toLocaleString("en-US")} tokens with the card, at 0036's estimate of ${ESTIMATED_BYTES_PER_TOKEN} bytes a token. ` +
-            `A budget is yours to declare: 0036 offers the larger of ${OFFER_FLOOR_TOKENS.toLocaleString("en-US")} tokens and that, ` +
-            `${Math.max(OFFER_FLOOR_TOKENS, tokens).toLocaleString("en-US")}, as \`context.always.budget.tokens\`, beside a \`context.ratio\` Claude Code's exact count measured here`,
-    );
+    say(`init: Claude Code project guidance is ~${tokens.toLocaleString("en-US")} tokens with the compiled card, at the illustrative ${ESTIMATED_BYTES_PER_TOKEN} B/token estimate.`);
+    if (!interviewing) say(`init: A budget is yours to declare: use the larger of ${OFFER_FLOOR_TOKENS.toLocaleString("en-US")} tokens and the two project guidance estimates at your explicit context.ratio. Interactive init projects both formats before asking. A provider count is an estimate; actual host usage may differ.`);
     const offer = offerText(splitOffers(target, { ratio: ESTIMATED_BYTES_PER_TOKEN, floor: OFFER_FLOOR_TOKENS }));
     if (offer !== null) say(`init: ${offer}`);
 }
 
 function reportLifetime(answers, say) {
+    if (answers.handoffBudget && answers.handoffBudget !== "none") say("init: handoff budgets and supplied ratio declared at 2.15; index checks the cap and complete window; ratio provenance is not proof of calibration");
+    else if (answers.handoffBudget !== "none") say(`init: ${HANDOFF_OFFER} Use --handoff-budget with JSON record_tokens and/or index_tokens plus ratio {bytes_per_token, calibrated_by}; the record cutoff is set when writing.`);
     const lifetime = answers.cacheLifetime ?? null;
     if (lifetime !== null) {
         say(
@@ -1070,8 +1121,139 @@ function terminal() {
     };
 }
 
+function prepareHandoffCutoff(target, answers) {
+    const handoffToday = new Date().toISOString().slice(0, 10);
+    let handoffNewest;
+    if (handoffOffer(answers.handoffBudget, { today: handoffToday })?.handoffs.series) {
+        try {
+            let present = true;
+            for (const rel of [".portulan", ".portulan/handoffs"]) {
+                let stat;
+                try { stat = fs.lstatSync(path.join(target, rel)); }
+                catch (error) { if (error.code !== "ENOENT") throw error; present = false; break; }
+                if (!stat.isDirectory()) throw new InitError(`${rel} is not an ordinary owned handoff directory`);
+            }
+            if (present) for (const record of handoffEntries(target, { slots: { handoffs: ".portulan/handoffs" } })) {
+                const date = eligibleHandoffDate(record.file, handoffToday);
+                if (date === null) throw new InitError(`${record.file} must lead with a valid YYYY-MM-DD date no more than a day after ${handoffToday} (UTC); rename the handoff`);
+                if (date > (handoffNewest ?? "")) handoffNewest = date;
+            }
+        } catch (error) { throw new CutoffError(`cannot establish the handoff cutoff: ${error.message}`); }
+    }
+    return { handoffToday, handoffNewest };
+}
+
+function prepareDraft(target, answers, beforeConsent = false) {
+    const handoff = prepareHandoffCutoff(target, answers);
+    const parent = outsideTempParents(target)[0];
+    if (!parent && beforeConsent) throw new InitError("no external location for bounded pre-consent preparation");
+    const env = parent ? { ...process.env, TMPDIR: parent, TMP: parent, TEMP: parent } : process.env;
+    const observed = scan(target, { comments: answers.residence !== "pointer", env });
+    return { observed, ...handoff, env, ignoreLines: answers.residence === "pointer" ? [] : claudeRulesUnignore(target, gitIn(target, { env, timeout: 1000, noFsmonitor: true })).lines };
+}
+
+function preparedFiles(target, answers, preparation) {
+    const files = draft({ ...answers, handoffToday: preparation.handoffToday, handoffNewest: preparation.handoffNewest }, preparation.observed);
+    if (files.has(".gitignore")) files.get(".gitignore").append.push(...(preparation.ignoreLines.length ? ["", ...preparation.ignoreLines] : []));
+    for (const [rel, file] of files) {
+        if (!file.append) continue;
+        let before = null;
+        try { before = readOwnedBytes(path.join(target, rel), target); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+        file.appendBefore = before;
+        file.contents = withIgnoreLines(before, file.append);
+    }
+    return files;
+}
+
+function checkAppendBaseline(target, files) {
+    for (const [rel, file] of files) {
+        if (!file.append) continue;
+        let current = null;
+        try { current = readOwnedBytes(path.join(target, rel), target); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+        if (current === null ? file.appendBefore !== null : file.appendBefore === null || !current.equals(file.appendBefore)) {
+            throw new InitError(`${rel} changed during confirmation; nothing written — run init again to prepare a fresh draft`);
+        }
+    }
+}
+
+function cutoffAt(answers, preparation) {
+    return handoffOffer(answers.handoffBudget, { today: preparation?.handoffToday, newest: preparation?.handoffNewest })?.handoffs.series?.budget.cutoff ?? null;
+}
+
+function checkConfirmedCutoff(answers, preparation) {
+    if (answers.confirmedCutoff !== cutoffAt(answers, preparation)) {
+        throw new InitError("the handoff cutoff changed during confirmation; nothing written — run init again to review the current cutoff");
+    }
+}
+
+function checkAcceptedBudget(target, answers, files) {
+    if (!answers.alwaysBudget) return;
+    const { tokens, ratio } = answers.alwaysBudget;
+    let measured;
+    try {
+        measured = previewAlways(target, files);
+        if (measured.after === null) throw new Error("projected guidance could not be measured");
+    } catch (error) {
+        throw new InitError(`the accepted always-tier budget can no longer be checked: ${error.message}; nothing written — run init again`);
+    }
+    const required = Math.max(...[...measured.before, ...measured.after].map(bytes => tokensOf(bytes, ratio.bytes_per_token)));
+    if (required > tokens) {
+        throw new InitError(`project guidance changed: the accepted ${tokens} tokens no longer cover ${required} tokens; nothing written — run init again to review a fresh offer`);
+    }
+}
+
+function projectedAlways(target, answers, ratio) {
+    if (!answers.preparation) answers.preparation = prepareDraft(target, answers, true);
+    let tokens = OFFER_FLOOR_TOKENS;
+    for (let pass = 0; pass < 8; pass++) {
+        const files = preparedFiles(target, { ...answers, alwaysBudget: { tokens, ratio } }, answers.preparation);
+        const clash = collisions(target, files);
+        if (clash.length) throw new InitError("drafted paths conflict with existing files");
+        const measured = previewAlways(target, files);
+        const next = Math.max(OFFER_FLOOR_TOKENS, ...[...measured.before, ...measured.after].map(bytes => tokensOf(bytes, ratio.bytes_per_token)));
+        if (next === tokens) return { tokens, files };
+        tokens = next;
+    }
+    throw new InitError("the self-counting budget did not converge");
+}
+
+async function alwaysInterview(answers, io, target, ask) {
+    const unavailable = error => {
+        if (error instanceof CutoffError) throw error;
+        io.say(`Always-tier offer unavailable: ${error.message}. No always cap will be declared; you may continue or cancel at confirmation.`);
+    };
+    const shared = handoffOffer(answers.handoffBudget)?.context.ratio;
+    const illustrative = shared ?? { bytes_per_token: ESTIMATED_BYTES_PER_TOKEN, calibrated_by: "illustrative-estimate" };
+    let preview;
+    try { preview = projectedAlways(target, answers, illustrative); }
+    catch (error) { unavailable(error); return; }
+    io.say(`Always-tier projected offer: ${preview.tokens.toLocaleString("en-US")} tokens at ${illustrative.bytes_per_token} B/token${shared ? " (your supplied ratio)" : " (illustrative estimate)"}. Covers the larger of today's and projected Claude Code project guidance and root AGENTS.md, never their sum. Excludes personal/global instructions, system/tools/MCP and later-loaded bodies.`);
+    const decision = await io.ask("Declare an always-tier budget? [y/N]: ");
+    if (decision === null) throw new InitError("no answer — the interview ended before it finished, and nothing was written");
+    if (!/^y(es)?$/i.test(decision.trim())) return;
+    let ratio = shared;
+    if (!ratio) {
+        const raw = await ask("Measured ratio JSON {bytes_per_token, calibrated_by}", { validate: value => {
+            try {
+                const ratio = JSON.parse(value); declaredContext({ context: { ratio } });
+                return SLUG.test(ratio.calibrated_by) ? null : "the calibration reference must be a slug";
+            } catch (error) { return error.message; }
+        } });
+        ratio = JSON.parse(raw);
+    }
+    let offered;
+    try { offered = projectedAlways(target, answers, ratio); }
+    catch (error) { unavailable(error); return; }
+    io.say("A provider count is an estimate with framing and domain limits; the supplied ratio is your assessment, not calibration verified by init.");
+    const accepted = await io.ask(`Accept ${offered.tokens.toLocaleString("en-US")} tokens at ${ratio.bytes_per_token} B/token (${ratio.calibrated_by})? [y/N]: `);
+    if (accepted === null) throw new InitError("no answer — the interview ended before it finished, and nothing was written");
+    if (/^y(es)?$/i.test(accepted.trim())) { answers.alwaysBudget = { tokens: offered.tokens, ratio }; answers.preparedFiles = offered.files; }
+}
+
 /** Asks for what the flags and the answers file did not give, and fills `answers` in place. */
-export async function interview(answers, { io, target, derivedName }) {
+export async function interview(answers, { io, target, derivedName, offer }) {
     const ask = async (prompt, { fallback = null, validate = () => null } = {}) => {
         for (;;) {
             const raw = await io.ask(fallback === null ? `${prompt}: ` : `${prompt} [${fallback}]: `);
@@ -1155,7 +1337,31 @@ export async function interview(answers, { io, target, derivedName }) {
         }
     }
 
+    if (answers.residence === "in-repo" && !answers.given.has("handoff-budget")) {
+        io.say(HANDOFF_OFFER);
+        answers.handoffBudget = await ask("Handoff budgets JSON: record_tokens and/or index_tokens, plus ratio {bytes_per_token, calibrated_by}; `none` to decline", {
+            fallback: "none",
+            validate: value => { try { handoffOffer(value); return null; } catch (error) { return error.message; } },
+        });
+    }
+
+    if (answers.residence === "in-repo") {
+        offer = typeof offer === "function" ? offer() : offer ?? spendOffer(target);
+        for (const line of spendOfferLines(offer)) io.say(line);
+        if (!answers.given.has("multipliers")) {
+            const raw = await io.ask("Declare the offered price multipliers? [y/N]: ");
+            if (raw === null) throw new InitError("no answer — the interview ended before it finished, and nothing was written");
+            if (/^y(es)?$/i.test(raw.trim())) answers.multipliers = JSON.stringify(offer.multipliers);
+        }
+        if (!answers.given.has("horizon")) {
+            const value = await ask("Requests still to go (`none` to leave undeclared)", { fallback: "none", validate: v => v === "none" || /^[1-9]\d*$/.test(v) && Number.isSafeInteger(Number(v)) ? null : "give a positive integer or `none`" });
+            if (value !== "none") answers.horizon = value;
+        }
+        answers.spend = spendAnswers(answers);
+    }
+
     io.say("");
+    if (answers.residence === "in-repo") await alwaysInterview(answers, io, target, ask);
     io.say("init: about to draft");
     io.say(`  residence   ${answers.residence}`);
     io.say(`  name        ${answers.name}`);
@@ -1165,6 +1371,13 @@ export async function interview(answers, { io, target, derivedName }) {
         io.say(`  feed        ${answers.feed ?? "(none)"}`);
     } else {
         io.say(`  cycle       ${answers.cycle ? answers.checkpoints : "(none — composing no packs)"}`);
+        if (answers.preparation) answers.preparedFiles ??= preparedFiles(target, answers, answers.preparation);
+        const handoff = answers.preparation ?? prepareHandoffCutoff(target, answers);
+        const offered = handoffOffer(answers.handoffBudget, { today: handoff.handoffToday, newest: handoff.handoffNewest });
+        answers.confirmedCutoff = offered?.handoffs.series?.budget.cutoff ?? null;
+        io.say(`  handoffs    ${offered ? JSON.stringify(offered) : "(none — no handoff budgets declared)"}`);
+        io.say(`  always      ${answers.alwaysBudget ? JSON.stringify(answers.alwaysBudget) : "(none — no always cap declared)"}`);
+        io.say(`  spend       ${answers.spend ? JSON.stringify(answers.spend) : "(none — undeclared general figures)"}`);
         io.say(
             `  cache       ${
                 answers.cacheLifetime ? `${answers.cacheLifetime}, as \`sessions.cache_lifetime\` at Workspace Definition ${SESSIONS_SPEC}` : "(none — the host's default lifetime)"
@@ -1203,7 +1416,10 @@ export function usage() {
         "                                 `compile` writes as Claude Code's `promptCacheTtl`. Unset,",
         "                                 the host's default stands and five minutes is offered.",
         "  --answers <file>               A JSON object of answers. Flags override its keys.",
+        "  --handoff-budget <JSON|none>   Optional record_tokens/index_tokens plus explicit ratio; cutoff set at write time.",
         "  --no-interview                 Never ask, even at a terminal: refuse instead, naming the flag.",
+        "  --multipliers <JSON>           In-repo: declare spend.multipliers (read and both write lifetimes).",
+        "  --horizon <requests>           In-repo: declare spend.horizon.requests, a positive integer.",
         "",
         "Exit codes: 0 it wrote · 2 it wrote nothing. There is no 1: init renders no verdict.",
         "",
@@ -1246,16 +1462,18 @@ export async function run(argv, options = {}) {
             );
         }
         if (!stat.isDirectory()) throw new InitError(`\`${parsed.target}\` is not a directory`);
+        try{assertNoSourceJournal(target);}catch(error){throw new InitError(error.message);}
 
         const answers = resolveAnswers(parsed.flags);
         const derivedName = slugify(path.basename(target));
 
         const io = options.io ?? terminal();
         const interviewing = io.interactive && !parsed.flags.noInterview;
+        let offer = null;
         if (interviewing) {
             // Asked before the questions too, so nobody answers them to be told the repository is already governed.
             refuseIfGoverned(residenceAt(target), parsed.target);
-            await interview(answers, { io, target, derivedName });
+            await interview(answers, { io, target, derivedName, offer: () => spendOffer(target, { env: options.env, ...options.spendHost }) });
         }
 
         if (answers.name === null) answers.name = derivedName;
@@ -1268,6 +1486,7 @@ export async function run(argv, options = {}) {
         validateAnswers(answers);
 
         refuseIfGoverned(residenceAt(target), parsed.target);
+        try{assertNoSourceJournal(target);}catch(error){throw new InitError(error.message);}
 
         let packAdvice = null;
         if (answers.residence === "in-repo" && answers.cycle) {
@@ -1295,13 +1514,10 @@ export async function run(argv, options = {}) {
             packAdvice = { resolved, why: expanded.why, inTree: resolvedAt !== null && resolvedAt === path.join(target, "packs") };
         }
 
-        const observed = scan(target, { comments: answers.residence !== "pointer" });
-        const files = draft(answers, observed);
-
-        if (files.has(".gitignore")) {
-            const { lines } = claudeRulesUnignore(target);
-            if (lines.length) files.get(".gitignore").append.push("", ...lines);
-        }
+        if (answers.preparedFiles) checkAppendBaseline(target, answers.preparedFiles);
+        const preparation = prepareDraft(target, answers);
+        const observed = preparation.observed;
+        const files = preparedFiles(target, answers, preparation);
 
         const clash = collisions(target, files);
         if (clash.length) {
@@ -1322,6 +1538,13 @@ export async function run(argv, options = {}) {
             );
         }
 
+        checkAppendBaseline(target, files);
+        if (interviewing && answers.residence === "in-repo") {
+            checkConfirmedCutoff(answers, preparation);
+            checkAcceptedBudget(target, answers, files);
+            checkConfirmedCutoff(answers, { ...preparation, handoffToday: new Date().toISOString().slice(0, 10) });
+        }
+
         // The manifest last: a run failing midway leaves no torso that `residenceAt` would read as a governed repository.
         const manifest = ".portulan/workspace.json";
         const left = [];
@@ -1332,16 +1555,6 @@ export async function run(argv, options = {}) {
                 continue;
             }
             fs.mkdirSync(path.dirname(full), { recursive: true });
-            if (file.append !== undefined) {
-                let before = null;
-                try {
-                    before = fs.readFileSync(full, "utf8");
-                } catch (error) {
-                    if (error.code !== "ENOENT") throw error;
-                }
-                fs.writeFileSync(full, withIgnoreLines(before, file.append));
-                continue;
-            }
             fs.writeFileSync(full, file.contents);
             if (file.mode !== undefined) fs.chmodSync(full, file.mode);
         }
@@ -1354,8 +1567,10 @@ export async function run(argv, options = {}) {
         );
         for (const rel of left) say(`init: left the repository's own \`${rel}\` as it is`);
         if (answers.residence !== "pointer") {
-            reportCard(target, say, warn);
+            reportCard(target, say, warn, interviewing, preparation.env);
             reportLifetime(answers, say);
+            if (!interviewing) for (const line of spendOfferLines(offer ?? spendOffer(target, { env: options.env, ...options.spendHost }))) say(`init: ${line}`);
+            if (answers.spend) say(`init: declared spend ${JSON.stringify(answers.spend)} (available since spec 2.12); run portulan compile to carry it into advisory commands`);
         }
         if (answers.residence === "pointer") {
             say(`init: this repository is recorded as governed by \`${answers.governedBy}\`. Nothing was fetched.`);