project-tiny-context-harness 0.11.0 → 0.12.0

package/dist/lib/package-json-config.js

@@ -1,6 +1,10 @@
 import path from "node:path";
-import { pathExists, readText, writeTextIfChanged } from "./fs.js";
-import { normalizeHarnessFolderName } from "./harness-root.js";
+import { pathExists, readText } from "./fs.js";
+import { normalizeHarnessFolderName, harnessRoot } from "./harness-root.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { assertSupportedSchema, rawSchemaVersion } from "./schema-guard.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { writeMaintenanceText } from "./maintenance-write.js";
 export async function packageHarnessRoot(projectRoot) {
     const packagePath = path.join(projectRoot, "package.json");
     if (!(await pathExists(packagePath))) {
@@ -17,25 +21,34 @@ export async function packageHarnessRoot(projectRoot) {
         : undefined;
 }
 export async function writePackageHarnessRoot(projectRoot, folderName) {
-    const normalized = normalizeHarnessFolderName(folderName);
-    const packagePath = path.join(projectRoot, "package.json");
-    const packageJson = (await pathExists(packagePath))
-        ? parsePackageJson(await readText(packagePath))
-        : {};
-    const existingConfig = packageJson.tyContext;
-    const nextConfig = existingConfig &&
-        typeof existingConfig === "object" &&
-        !Array.isArray(existingConfig)
-        ? {
-            ...existingConfig,
-            harnessFolderName: normalized,
-        }
-        : { harnessFolderName: normalized };
-    const next = {
-        ...packageJson,
-        tyContext: nextConfig,
-    };
-    return writeTextIfChanged(packagePath, `${JSON.stringify(next, null, 2)}\n`);
+    await assertSupportedSchema(projectRoot, "init");
+    return withMaintenanceLock(projectRoot, "sync", async () => {
+        await assertSupportedSchema(projectRoot, "init");
+        const normalized = normalizeHarnessFolderName(folderName);
+        const current = await harnessRoot(projectRoot);
+        if (current !== normalized &&
+            ((await rawSchemaVersion(projectRoot)) !== undefined ||
+                (await captureMutationFileState(projectRoot, `${normalized}/config.yaml`)).exists))
+            throw new Error("init cannot relocate or switch an existing installation; preserve both configurations and migrate the root explicitly");
+        const before = await captureMutationFileState(projectRoot, "package.json");
+        const packageJson = before.exists
+            ? parsePackageJson(Buffer.from(before.bytes_base64, "base64").toString("utf8"))
+            : {};
+        const existingConfig = packageJson.tyContext;
+        const nextConfig = existingConfig &&
+            typeof existingConfig === "object" &&
+            !Array.isArray(existingConfig)
+            ? {
+                ...existingConfig,
+                harnessFolderName: normalized,
+            }
+            : { harnessFolderName: normalized };
+        const next = {
+            ...packageJson,
+            tyContext: nextConfig,
+        };
+        return writeMaintenanceText(projectRoot, "package.json", `${JSON.stringify(next, null, 2)}\n`, before);
+    });
 }
 function parsePackageJson(content) {
     const parsed = JSON.parse(content);

package/dist/lib/package-source.js

@@ -1,17 +1,25 @@
 import { createHash } from "node:crypto";
-import { promises as fs } from "node:fs";
 import path from "node:path";
-import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged, } from "./fs.js";
+import { listFiles, pathExists, readText, } from "./fs.js";
 import { AGENTS_BLOCK_MARKERS } from "./managed-file.js";
 import { SOURCE_MAPPINGS_PATH } from "./paths.js";
 import { parseYaml } from "./yaml.js";
+import { assertSupportedSchema } from "./schema-guard.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { writeMaintenanceText, removeMaintenanceFile, } from "./maintenance-write.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { resolveInsideRepository, ensureSafeRepositoryDirectory, } from "./repository-path-safety.js";
 export async function syncSource(projectRoot) {
-    const report = { changed: [] };
-    for (const mapping of await readSourceMappings(projectRoot)) {
-        const changed = await applyMapping(projectRoot, mapping);
-        report.changed.push(...changed);
-    }
-    return report;
+    await assertSupportedSchema(projectRoot, "package sync-source");
+    return withMaintenanceLock(projectRoot, "sync", async () => {
+        await assertSupportedSchema(projectRoot, "package sync-source");
+        const report = { changed: [] };
+        for (const mapping of await readSourceMappings(projectRoot)) {
+            const changed = await applyMapping(projectRoot, mapping);
+            report.changed.push(...changed);
+        }
+        return report;
+    });
 }
 export async function checkSource(projectRoot) {
     const drift = [];
@@ -55,17 +63,19 @@ async function readSourceMappings(projectRoot) {
     return parsed.source_mappings ?? [];
 }
 async function applyMapping(projectRoot, mapping) {
-    const target = path.join(projectRoot, mapping.target);
+    const target = resolveInsideRepository(projectRoot, mapping.target, "source_mapping_target");
     const rendered = await renderMapping(projectRoot, mapping);
     if (typeof rendered === "string") {
-        return (await writeTextIfChanged(target, rendered)) ? [mapping.target] : [];
+        return (await writeMaintenanceText(projectRoot, mapping.target, rendered))
+            ? [mapping.target]
+            : [];
     }
-    await ensureDir(target);
+    await ensureSafeRepositoryDirectory(projectRoot, mapping.target, "source_mapping_target");
     const changed = [];
     const expectedRelatives = new Set(rendered.map((item) => item.relative));
     for (const item of rendered) {
         const targetFile = path.join(target, item.relative);
-        if (await writeTextIfChanged(targetFile, item.content)) {
+        if (await writeMaintenanceText(projectRoot, path.relative(projectRoot, targetFile).replaceAll("\\", "/"), item.content)) {
             changed.push(`${mapping.target}/${item.relative}`);
         }
     }
@@ -75,14 +85,17 @@ async function applyMapping(projectRoot, mapping) {
         }
         const relative = path.relative(target, targetFile);
         if (!expectedRelatives.has(relative)) {
-            await fs.rm(targetFile, { force: true });
+            const targetRelative = path
+                .relative(projectRoot, targetFile)
+                .replaceAll("\\", "/");
+            await removeMaintenanceFile(projectRoot, targetRelative, await captureMutationFileState(projectRoot, targetRelative));
             changed.push(`${mapping.target}/${relative}`);
         }
     }
     return changed;
 }
 async function renderMapping(projectRoot, mapping) {
-    const source = path.join(projectRoot, mapping.source);
+    const source = resolveInsideRepository(projectRoot, mapping.source, "source_mapping_input");
     if (mapping.mode === "copy-file") {
         return readText(source);
     }

package/dist/lib/repository-path-safety.d.ts

@@ -4,6 +4,8 @@ export interface SafeRepositoryPath {
     absolute: string;
     relative: string;
 }
+/** Canonical, literal local file locator; this does not establish file existence. */
+export declare function normalizeRepositoryFile(value: string, label?: string): string;
 export declare function resolveInsideRepository(rootInput: string, relativeInput: string, label: string): string;
 export declare function assertProtectedRepositoryFile(repositoryInput: string, fileInput: string, label: string): Promise<string>;
 export declare function assertProtectedRepositoryDirectory(repositoryInput: string, directoryInput: string, label: string): Promise<string>;

package/dist/lib/repository-path-safety.js

@@ -1,5 +1,25 @@
 import { lstat, mkdir, realpath } from "node:fs/promises";
 import path from "node:path";
+/** Canonical, literal local file locator; this does not establish file existence. */
+export function normalizeRepositoryFile(value, label = "repository_file") {
+    if (/[\0\r\n\t]/u.test(value))
+        throw new Error(`unsafe_path:${label}:control_character`);
+    const slashed = value.replace(/\\/gu, "/");
+    const normalized = slashed.startsWith("./") ? slashed.slice(2) : slashed;
+    if (!normalized ||
+        path.posix.isAbsolute(normalized) ||
+        normalized.startsWith("//") ||
+        /^[A-Za-z]:/u.test(normalized))
+        throw new Error(`unsafe_path:${label}:${value}`);
+    const segments = normalized.split("/");
+    if (segments.some((segment) => !segment) || segments.includes(".."))
+        throw new Error(`unsafe_path:${label}:${value}`);
+    if (segments.includes("."))
+        throw new Error(`non_canonical_repository_path_dot_segment:${label}:${value}`);
+    if (/[*?\[\]{}]/u.test(normalized))
+        throw new Error(`unsupported_repository_path_syntax:${label}:${value}`);
+    return normalized;
+}
 export function resolveInsideRepository(rootInput, relativeInput, label) {
     if (!relativeInput || path.isAbsolute(relativeInput))
         throw new Error(`unsafe_path:${label}:${relativeInput}`);

package/dist/lib/retirement-assets.d.ts

@@ -0,0 +1,13 @@
+import type { MutationFileState } from "./context-mutation/mutation-types.js";
+export interface RetirementFile {
+    path: string;
+    before: MutationFileState;
+    after: string | null;
+    reason: string;
+}
+export interface RetirementAssets {
+    files: RetirementFile[];
+    blockers: string[];
+    review: string[];
+}
+export declare function inspectRetirementAssets(repository: string, root: string): Promise<RetirementAssets>;

package/dist/lib/retirement-assets.js

@@ -0,0 +1,182 @@
+import { readFile, readdir, lstat } from "node:fs/promises";
+import path from "node:path";
+import { packageRoot } from "./paths.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { assertProtectedRepositoryDirectory, resolveInsideRepository, } from "./repository-path-safety.js";
+import { MAKEFILE_BLOCK_START, MAKEFILE_BLOCK_END } from "./managed-file.js";
+export async function inspectRetirementAssets(repository, root) {
+    const inventory = JSON.parse(await readFile(path.join(packageRoot(), "migrations/schema-4-owned-assets.json"), "utf8"));
+    const result = { files: [], blockers: [], review: [] };
+    const knownPaths = new Set(inventory.files.map((asset) => asset.path.replace("{root}", root)));
+    const skillRoots = new Set([...knownPaths]
+        .filter((file) => file.startsWith(`${root}/skills/`))
+        .map((file) => file
+        .split("/")
+        .slice(0, root.split("/").length + 2)
+        .join("/")));
+    for (const skill of skillRoots) {
+        try {
+            await inspectExtraSkillFiles(repository, skill, knownPaths, result.blockers);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                result.blockers.push(`${skill}: ${String(error)}`);
+        }
+    }
+    for (const asset of inventory.files) {
+        const relative = asset.path.replace("{root}", root);
+        try {
+            const before = await captureMutationFileState(repository, relative);
+            if (!before.exists)
+                continue;
+            if (before.sha256 === asset.sha256)
+                result.files.push({
+                    path: relative,
+                    before,
+                    after: null,
+                    reason: "exact schema-4 package asset",
+                });
+            else if (relative.includes("/skills/") ||
+                relative === ".codex/agents/long-task-implementation.toml")
+                result.blockers.push(`${relative}: modified old executable guidance; preserve and explicitly reconcile before retirement`);
+            else
+                result.review.push(`${relative}: customized file retained; review any active old command dependencies`);
+        }
+        catch (error) {
+            result.blockers.push(`${relative}: ${String(error)}`);
+        }
+    }
+    const makefile = await captureMutationFileState(repository, "Makefile");
+    if (makefile.exists &&
+        !result.files.some((file) => file.path === "Makefile")) {
+        const content = Buffer.from(makefile.bytes_base64, "base64").toString("utf8");
+        if (content.includes(MAKEFILE_BLOCK_START) ||
+            content.includes(MAKEFILE_BLOCK_END)) {
+            const start = content.indexOf(MAKEFILE_BLOCK_START), end = content.indexOf(MAKEFILE_BLOCK_END);
+            const expected = [
+                MAKEFILE_BLOCK_START,
+                "# Included before project targets so project recipes win on name conflicts.",
+                `-include ${root}/ty-context-managed/make/ty-context.mk`,
+            ];
+            const block = content.slice(start, end + MAKEFILE_BLOCK_END.length);
+            if (start < 0 ||
+                end < start ||
+                content.indexOf(MAKEFILE_BLOCK_START, start + 1) >= 0 ||
+                content.indexOf(MAKEFILE_BLOCK_END, end + 1) >= 0 ||
+                ![
+                    expected.concat(MAKEFILE_BLOCK_END).join("\n"),
+                    expected.concat(".DEFAULT_GOAL :=", MAKEFILE_BLOCK_END).join("\n"),
+                ].includes(block.replaceAll("\r\n", "\n")))
+                result.blockers.push("Makefile: modified or malformed managed include; reconcile before removing its package target file");
+            else
+                result.files.push({
+                    path: "Makefile",
+                    before: makefile,
+                    after: content.slice(0, start) +
+                        content.slice(end + MAKEFILE_BLOCK_END.length),
+                    reason: "remove exact package include, preserve user targets",
+                });
+        }
+    }
+    const hooks = await captureMutationFileState(repository, ".codex/hooks.json");
+    if (hooks.exists) {
+        try {
+            const raw = JSON.parse(Buffer.from(hooks.bytes_base64, "base64").toString("utf8"));
+            if (!raw ||
+                typeof raw !== "object" ||
+                Array.isArray(raw) ||
+                (raw.hooks !== undefined &&
+                    (!raw.hooks ||
+                        typeof raw.hooks !== "object" ||
+                        Array.isArray(raw.hooks))))
+                throw new Error("unsupported hooks configuration shape");
+            let changed = false;
+            const next = structuredClone(raw);
+            for (const [event, groups] of Object.entries(next.hooks ?? {})) {
+                if (!Array.isArray(groups))
+                    continue;
+                next.hooks[event] = groups.flatMap((group) => {
+                    if (!group ||
+                        typeof group !== "object" ||
+                        !Array.isArray(group.hooks))
+                        return [group];
+                    const row = group;
+                    const retained = row.hooks.filter((entry) => {
+                        if (!isExactBaselineHook(entry, event)) {
+                            if (JSON.stringify(entry).includes("long-task-hook"))
+                                result.blockers.push(`.codex/hooks.json ${event}: customized old Hook requires reconciliation`);
+                            return true;
+                        }
+                        changed = true;
+                        return false;
+                    });
+                    if (retained.length === row.hooks.length)
+                        return [group];
+                    const expectedMatcher = event === "PreToolUse"
+                        ? "^(spawn_agent|Agent)$"
+                        : event === "SubagentStart"
+                            ? "^long_task_implementation$"
+                            : undefined;
+                    if (!retained.length &&
+                        row.matcher === expectedMatcher &&
+                        Object.keys(row).every((key) => ["hooks", "matcher"].includes(key)))
+                        return [];
+                    return [{ ...row, hooks: retained }];
+                });
+                if (!next.hooks[event].length)
+                    delete next.hooks[event];
+            }
+            if (changed)
+                result.files.push({
+                    path: ".codex/hooks.json",
+                    before: hooks,
+                    after: JSON.stringify(next, null, 2) + "\n",
+                    reason: "remove exact baseline Hook entries, preserve mixed user configuration",
+                });
+        }
+        catch (error) {
+            result.blockers.push(`.codex/hooks.json: ${String(error)}`);
+        }
+    }
+    return result;
+}
+async function inspectExtraSkillFiles(repository, relative, known, blockers) {
+    const target = resolveInsideRepository(repository, relative, "retirement_skill");
+    await lstat(target);
+    const safe = await assertProtectedRepositoryDirectory(repository, target, "retirement_skill");
+    for (const entry of await readdir(safe, { withFileTypes: true })) {
+        const child = `${relative}/${entry.name}`;
+        if (entry.isSymbolicLink())
+            blockers.push(`${child}: linked old Skill content requires explicit reconciliation`);
+        else if (entry.isDirectory())
+            await inspectExtraSkillFiles(repository, child, known, blockers);
+        else if (!known.has(child))
+            blockers.push(`${child}: additional user Skill content; preserve and reconcile before removing its owning Skill`);
+    }
+}
+function isExactBaselineHook(value, event) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    if (![
+        "PreToolUse",
+        "SessionStart",
+        "PostCompact",
+        "Stop",
+        "SubagentStart",
+    ].includes(event) ||
+        Object.keys(row).sort().join(",") !==
+            "command,commandWindows,statusMessage,timeout,type")
+        return false;
+    if (row.type !== "command" ||
+        row.statusMessage !== "Tiny Context long-task live authority gate" ||
+        row.timeout !== (event === "Stop" ? 3600 : 10) ||
+        row.commandWindows !== row.command ||
+        typeof row.command !== "string")
+        return false;
+    const matched = /^node "([^"\r\n]+)"$/.exec(row.command);
+    if (!matched ||
+        (!path.isAbsolute(matched[1]) && !path.win32.isAbsolute(matched[1])))
+        return false;
+    return /\/(?:node_modules\/project-tiny-context-harness|packages\/ty-context)\/dist\/long-task-hook\.js$/.test(matched[1].replaceAll("\\", "/"));
+}

package/dist/lib/retirement-binding.d.ts

@@ -0,0 +1,10 @@
+import type { MutationFileState } from "./context-mutation/mutation-types.js";
+export interface RetirementBinding {
+    common: string;
+    record: string;
+    marker_key: string;
+    marker: string | null;
+    before: MutationFileState;
+}
+export declare function inspectRetirementBinding(repository: string): Promise<RetirementBinding | null>;
+export declare function retireOwnBinding(repository: string, expected: RetirementBinding | null): Promise<void>;

package/dist/lib/retirement-binding.js

@@ -0,0 +1,59 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { gitCommonDir, gitConfigGet, gitConfigUnset } from "./git.js";
+import { sha256Hex } from "./strict-codec.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { removeMaintenanceFile } from "./maintenance-write.js";
+export async function inspectRetirementBinding(repository) {
+    let common;
+    try {
+        common = await gitCommonDir(repository);
+    }
+    catch (error) {
+        if (String(error).includes("not a git repository"))
+            return null;
+        throw error;
+    }
+    const resolved = path.resolve(repository).replaceAll("\\", "/");
+    const identity = "wt-" +
+        sha256Hex(process.platform === "win32" ? resolved.toLowerCase() : resolved);
+    const record = `ty-context/long-task/worktrees/${identity}/active.json`;
+    try {
+        await lstat(path.join(common, record + ".lock"));
+        throw new Error("retirement_blocked: old operation lock exists; settle it with the compatible old lifecycle. A lock does not establish host session state.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const before = await captureMutationFileState(common, record);
+    const marker_key = `ty-context.longTask.${identity}`;
+    const marker = await gitConfigGet(repository, marker_key);
+    if (before.exists) {
+        const active = JSON.parse(Buffer.from(before.bytes_base64, "base64").toString("utf8"));
+        const normalize = (value) => process.platform === "win32"
+            ? path.resolve(value).toLowerCase()
+            : path.resolve(value);
+        if (active.schema_version !== "active-long-task-authority-v3" ||
+            active.worktree_identity !== identity ||
+            typeof active.repository_root !== "string" ||
+            normalize(active.repository_root) !== normalize(repository))
+            throw new Error(`retirement_blocked: unsupported or mismatched old active record ${record}; resolve with compatible old tool`);
+    }
+    return { common, record, marker_key, marker, before };
+}
+export async function retireOwnBinding(repository, expected) {
+    if (!expected)
+        return;
+    const current = await inspectRetirementBinding(repository);
+    if (!current ||
+        current.common !== expected.common ||
+        current.record !== expected.record ||
+        (current.marker !== null && current.marker !== expected.marker) ||
+        (current.before.exists && current.before.sha256 !== expected.before.sha256))
+        throw new Error("retirement_blocked: current worktree binding changed; do not touch another worktree or changed record");
+    if (current.before.exists)
+        await removeMaintenanceFile(current.common, current.record, current.before);
+    if (current.marker !== null)
+        await gitConfigUnset(repository, current.marker_key);
+}

package/dist/lib/retirement-defaults.d.ts

@@ -0,0 +1,7 @@
+export declare function migrateDefaultBodySelection(content: string): {
+    content: string;
+    before: string[];
+    after: string[];
+    added: string[];
+    removed: string[];
+};

package/dist/lib/retirement-defaults.js

@@ -0,0 +1,29 @@
+import { parseContextManifest } from "./context-manifest-schema.js";
+import { selectDefaultContextPaths } from "./context-catalog/catalog-default-footprint.js";
+export function migrateDefaultBodySelection(content) {
+    const parsed = parseContextManifest(content);
+    if (!parsed.manifest || parsed.errors.length)
+        throw new Error(`Cannot migrate invalid manifest: ${parsed.errors.join("; ")}`);
+    if (parsed.manifest.default_files?.length)
+        throw new Error("Schema-4 manifest unexpectedly declares schema-5 default_files; review before migration.");
+    const before = [
+        ...new Set([
+            ...selectDefaultContextPaths(parsed.manifest).keys(),
+            "project_context/architecture.md",
+        ]),
+    ].sort();
+    // A direct read does not promote architecture to a traversal root.
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const next = `default_files = ["project_context/architecture.md"]${eol}${content}`;
+    const candidate = parseContextManifest(next);
+    if (!candidate.manifest || candidate.errors.length)
+        throw new Error(`Invalid migration candidate: ${candidate.errors.join("; ")}`);
+    const after = [
+        ...selectDefaultContextPaths(candidate.manifest).keys(),
+    ].sort();
+    const added = after.filter((value) => !before.includes(value));
+    const removed = before.filter((value) => !after.includes(value));
+    if (added.length || removed.length)
+        throw new Error(`Default body selection changed: added=${JSON.stringify(added)} removed=${JSON.stringify(removed)}`);
+    return { content: next, before, after, added, removed };
+}

package/dist/lib/retirement-plan.d.ts

@@ -0,0 +1,10 @@
+import { type RetirementFile } from "./retirement-assets.js";
+import { type RetirementBinding } from "./retirement-binding.js";
+export interface RetirementPlan {
+    files: RetirementFile[];
+    blockers: string[];
+    review: string[];
+    defaults: string[];
+    binding: RetirementBinding | null;
+}
+export declare function planSchema5Retirement(repository: string): Promise<RetirementPlan>;

package/dist/lib/retirement-plan.js

@@ -0,0 +1,96 @@
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { rawSchemaVersion } from "./schema-guard.js";
+import { harnessConfigPath, harnessRoot } from "./harness-root.js";
+import { parseYaml, stringifyYaml } from "./yaml.js";
+import { assertLegacyContextTransactionSettled } from "./retirement-preflight.js";
+import { migrateDefaultBodySelection } from "./retirement-defaults.js";
+import { inspectRetirementAssets, } from "./retirement-assets.js";
+import { inspectRetirementBinding, } from "./retirement-binding.js";
+import { prepareStartupInstructions } from "./sync-engine.js";
+import { loadContextCatalog } from "./context-catalog/catalog-load.js";
+import { inspectRetirementReferences } from "./retirement-references.js";
+export async function planSchema5Retirement(repository) {
+    const result = {
+        files: [],
+        blockers: [],
+        review: [],
+        defaults: [],
+        binding: null,
+    };
+    try {
+        await assertLegacyContextTransactionSettled(repository);
+        const version = await rawSchemaVersion(repository);
+        if (version === "5")
+            return result;
+        if (version !== "4")
+            throw new Error(`Automatic retirement supports schema 4 / package 0.11.0 only; found ${version ?? "no configuration"}. Use an explicitly compatible migration route, not old proof repair.`);
+        const root = await harnessRoot(repository);
+        const catalog = await loadContextCatalog(repository);
+        const errors = catalog.diagnostics.filter((entry) => entry.severity === "error");
+        if (errors.length)
+            throw new Error(errors.map((entry) => entry.message).join("; "));
+        result.binding = await inspectRetirementBinding(repository);
+        const assets = await inspectRetirementAssets(repository, root);
+        result.files.push(...assets.files);
+        result.blockers.push(...assets.blockers);
+        result.review.push(...assets.review);
+        const manifest = await captureMutationFileState(repository, "project_context/context.toml");
+        const defaults = migrateDefaultBodySelection(Buffer.from(manifest.bytes_base64, "base64").toString("utf8"));
+        result.defaults = defaults.after;
+        result.files.push({
+            path: "project_context/context.toml",
+            before: manifest,
+            after: defaults.content,
+            reason: "preserve exact default body selection without promoting traversal roots",
+        });
+        const configPath = await harnessConfigPath(repository);
+        const config = await captureMutationFileState(repository, configPath);
+        const raw = parseYaml(Buffer.from(config.bytes_base64, "base64").toString("utf8"));
+        const known = new Set([
+            "AGENTS.md",
+            "Makefile",
+            "tools",
+            ".github/workflows/harness.yml",
+            `${root}/skills`,
+            `${root}/ty-context-managed/context_templates`,
+            `${root}/ty-context-managed/make/ty-context.mk`,
+            `${root}/ty-context-managed/templates`,
+            `${root}/ty-context-managed/policies`,
+        ]);
+        if (raw.managed_files !== undefined && !Array.isArray(raw.managed_files))
+            throw new Error(`${configPath}: managed_files must be an array`);
+        for (const entry of (raw.managed_files ?? []))
+            if (!entry || !known.has(String(entry.path).replaceAll("\\", "/")))
+                result.blockers.push(`${configPath}: unsupported managed entry ${entry?.path ?? "unknown"}; preserve and reconcile explicitly`);
+        const next = {
+            ...raw,
+            core: { ...raw.core, schema_version: "5" },
+            managed_files: [{ path: "AGENTS.md", strategy: "merge-block" }],
+        };
+        delete next.profiles;
+        delete next.modularity;
+        result.files.push({
+            path: configPath,
+            before: config,
+            after: stringifyYaml(next),
+            reason: "schema-5 configuration; preserve unrelated user fields",
+        });
+        const startup = await prepareStartupInstructions(repository);
+        result.blockers.push(...startup.blocked);
+        if (startup.content !== undefined)
+            result.files.push({
+                path: "AGENTS.md",
+                before: startup.before,
+                after: startup.content,
+                reason: "publish the short development contract last",
+            });
+        const references = await inspectRetirementReferences(repository, catalog, result.files);
+        result.blockers.push(...references.blockers);
+        result.review.push(...references.review);
+        result.review.push("Review nonmanaged Context, local Skills, AGENTS overrides and build configuration for still-effective old instructions. Historical mentions alone are not blockers. Existing ordinary Markdown/direct JSON/YAML values remain readable; live compact/symbolic/compiler-dependent resources must be extracted or replaced with provenance before information migration can be claimed complete.");
+    }
+    catch (error) {
+        result.blockers.push(String(error));
+    }
+    return result;
+}

package/dist/lib/retirement-preflight.d.ts

@@ -0,0 +1,2 @@
+export declare const COMPATIBLE_SCHEMA4_CLI = "npx --yes --package project-tiny-context-harness@0.11.0 ty-context";
+export declare function assertLegacyContextTransactionSettled(repository: string): Promise<void>;

package/dist/lib/retirement-preflight.js

@@ -0,0 +1,13 @@
+import { readContextMutationJournal } from "./context-mutation/mutation-journal.js";
+export const COMPATIBLE_SCHEMA4_CLI = "npx --yes --package project-tiny-context-harness@0.11.0 ty-context";
+export async function assertLegacyContextTransactionSettled(repository) {
+    let journal;
+    try {
+        journal = await readContextMutationJournal(repository);
+    }
+    catch (error) {
+        throw new Error(`retirement_blocked: cannot read existing Context transaction: ${String(error)}. Use an explicitly compatible recovery tool; do not treat unreadable state as no transaction. Schema and old recovery dependencies have not been switched.`);
+    }
+    if (journal)
+        throw new Error(`retirement_blocked: unfinished Context transaction ${journal.transaction_id}. Before upgrading, use the compatible installed 0.11.0 CLI or ${COMPATIBLE_SCHEMA4_CLI} context transaction status, then complete or rollback. If a conflicting Long-Task binding prevents recovery, legitimately end or abandon it with that compatible CLI first; no old Final Gate is required and deleting a lock is not recovery. Recheck before retrying upgrade.`);
+}

package/dist/lib/retirement-references.d.ts

@@ -0,0 +1,6 @@
+import type { ContextCatalog } from "./context-catalog/catalog-types.js";
+import type { RetirementFile } from "./retirement-assets.js";
+export declare function inspectRetirementReferences(repository: string, catalog: ContextCatalog, changes: RetirementFile[]): Promise<{
+    blockers: string[];
+    review: string[];
+}>;