agentera 3.0.0-dev.2 → 3.0.0-dev.20

package/dist/hooks/validateArtifact/traversal.js

@@ -0,0 +1,106 @@
+/**
+ * Path resolution and artifact identification.
+ *
+ * Given an arbitrary `cwd` and a candidate write path, decide which
+ * (if any) protocol-tracked artifact the write targets, applying
+ * `.agentera/docs.yaml` path overrides when present.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePath } from "../../core/paths.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS, normalizeArtifactProtocolId, } from "../../registries/artifactProtocolIds.js";
+import { DEFAULT_ARTIFACT_PATHS } from "../common.js";
+import { COMPACTABLE_YAML_ARTIFACTS, compactFile, compactYamlFile } from "../compaction/index.js";
+import { isMapping } from "./schema.js";
+const AGENT_YAML_RE = /\.agentera\/([a-z_]+)\.yaml$/;
+function resolvePathRel(fp, cwd) {
+    return path.isAbsolute(fp) ? fp : path.join(cwd, fp);
+}
+function docsPathOverrides(cwd) {
+    const docsPath = path.join(cwd, ".agentera", "docs.yaml");
+    if (!fs.existsSync(docsPath) || !fs.statSync(docsPath).isFile())
+        return {};
+    let data;
+    try {
+        // cast: docs.yaml path-override mapping parsed from a YAML file
+        data = loadYamlMapping(fs.readFileSync(docsPath, "utf8"));
+    }
+    catch (exc) {
+        process.stderr.write(`warning: failed to load docs path overrides: ${exc.message}\n`);
+        return {};
+    }
+    const mapping = data.mapping;
+    if (!Array.isArray(mapping))
+        return {};
+    const overrides = {};
+    for (const entry of mapping) {
+        if (!isMapping(entry))
+            continue;
+        const artifact = entry.artifact;
+        const p = entry.path;
+        if (typeof artifact === "string" && typeof p === "string")
+            overrides[artifact] = p;
+    }
+    return overrides;
+}
+export function defaultArtifactPath(artifact, cwd) {
+    const rel = docsPathOverrides(cwd)[artifact] ?? DEFAULT_ARTIFACT_PATHS[artifact] ?? "";
+    return rel ? resolvePathRel(rel, cwd) : "";
+}
+export function artifactPaths(cwd) {
+    const paths = { ...DEFAULT_ARTIFACT_PATHS, ...docsPathOverrides(cwd) };
+    const resolved = {};
+    for (const [artifact, p] of Object.entries(paths))
+        resolved[artifact] = resolvePathRel(p, cwd);
+    return resolved;
+}
+function samePath(left, right) {
+    return resolvePath(left) === resolvePath(right);
+}
+export function artifactForWrite(absPath, relPath, basename, cwd) {
+    for (const [artifact, mappedPath] of Object.entries(artifactPaths(cwd))) {
+        if (samePath(absPath, mappedPath))
+            return artifact;
+    }
+    const match = AGENT_YAML_RE.exec(relPath);
+    if (match) {
+        const id = match[1];
+        return id in ARTIFACT_PROTOCOL_PATHS ? id : null;
+    }
+    if (HUMAN_FACING_ARTIFACT_IDS.has(normalizeArtifactProtocolId(basename) ?? "")) {
+        return normalizeArtifactProtocolId(basename);
+    }
+    return null;
+}
+function readIfNeeded(content, absPath) {
+    if (content !== null && content !== undefined)
+        return content;
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function compactAfterValidWrite(artifact, absPath) {
+    if (!fs.existsSync(absPath))
+        return [];
+    try {
+        if (artifact === "todo") {
+            compactFile(absPath, "todo-resolved");
+        }
+        else if (artifact in COMPACTABLE_YAML_ARTIFACTS) {
+            compactYamlFile(absPath, artifact);
+        }
+        else {
+            return [];
+        }
+    }
+    catch (exc) {
+        return [`${artifact}: compaction failed: ${exc.message}`];
+    }
+    return [];
+}
+export { readIfNeeded, compactAfterValidWrite };
+//# sourceMappingURL=traversal.js.map

package/dist/hooks/validateArtifact/traversal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traversal.js","sourceRoot":"","sources":["../../../src/hooks/validateArtifact/traversal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,MAAM,aAAa,GAAG,8BAA8B,CAAC;AAErD,SAAS,cAAc,CAAC,EAAU,EAAE,GAAW;IAC7C,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,CAAC;IAC3E,IAAI,IAAgB,CAAC;IACrB,IAAI,CAAC;QACH,gEAAgE;QAChE,IAAI,GAAG,eAAe,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAe,CAAC;IAC1E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gDAAiD,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QACjG,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;QACrB,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,GAAW;IAC/D,MAAM,GAAG,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,sBAAsB,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACvF,OAAO,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,KAAK,GAA2B,EAAE,GAAG,sBAAsB,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/F,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/F,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,KAAa;IAC3C,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAe,EAAE,QAAgB,EAAE,GAAW;IAC9F,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACxE,IAAI,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;YAAE,OAAO,QAAQ,CAAC;IACrD,CAAC;IACD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,OAAO,EAAE,IAAI,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACnD,CAAC;IACD,IAAI,yBAAyB,CAAC,GAAG,CAAC,2BAA2B,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/E,OAAO,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,OAAsB,EAAE,OAAe;IAC3D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,QAAgB,EAAE,OAAe;IAC/D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;YACxB,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QACxC,CAAC;aAAM,IAAI,QAAQ,IAAI,0BAA0B,EAAE,CAAC;YAClD,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,QAAQ,wBAAyB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/hooks/validateArtifact/violations.js

@@ -0,0 +1,108 @@
+/**
+ * YAML-side violation orchestrators.
+ *
+ * `validateYamlContent` is the single entry point: parse, walk the
+ * schema singleton groups, run sequence validation, apply artifact-
+ * specific rules (plan, decisions), and finally run BUDGET and
+ * VALIDATION_RULES checks. Lower-level helpers live in `schema.ts`.
+ */
+import path from "node:path";
+import { parseYaml } from "../../core/yaml.js";
+import { resolveSourceRoot } from "../../core/sourceRoot.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { expectedSequenceOrder, isMapping, sequenceInOrder, validationRuleSeverity, validateDecisionAlternatives, validateDecisionSatisfaction, validateFullPlanContract, validatePlanDependencies, validatePlanKnownFields, validateSequences, validateSingletonGroup, collectSingletonGroups, wordCount, } from "./schema.js";
+function schemasDirDefault() {
+    return path.join(resolveSourceRoot(), "skills", "agentera", "schemas", "artifacts");
+}
+export function validateYamlContent(content, schema, name) {
+    const violations = [];
+    let data;
+    try {
+        data = parseYaml(content);
+    }
+    catch (exc) {
+        return [`${name}: invalid YAML: ${exc.message}`];
+    }
+    if (!isMapping(data)) {
+        return [`${name}: root must be a mapping`];
+    }
+    for (const [group, groupLower, fields] of collectSingletonGroups(schema)) {
+        let scope;
+        if (groupLower in data && isMapping(data[groupLower])) {
+            scope = data[groupLower];
+        }
+        else if (fields.some((f) => f in data)) {
+            scope = data;
+        }
+        else {
+            continue;
+        }
+        validateSingletonGroup(violations, name, schema, group, scope, groupLower);
+    }
+    if (name === "plan") {
+        validatePlanKnownFields(data, schema, violations);
+        validateFullPlanContract(data, violations);
+        validatePlanDependencies(data, violations);
+    }
+    validateSequences(data, schema, name, violations);
+    if (name === "decisions") {
+        violations.push(...validateDecisionAlternatives(data, name));
+        violations.push(...validateDecisionSatisfaction(data, name));
+    }
+    const wordBudgetSeverity = validationRuleSeverity(schema, "word_budget");
+    for (const be of Object.values(schema.BUDGET ?? {})) {
+        if (!isMapping(be))
+            continue;
+        const mw = be.max_words;
+        const scope = be.scope ?? "";
+        if (mw && String(scope).includes("full_file") && wordBudgetSeverity === "error") {
+            const wc = wordCount(content);
+            if (wc > Number(mw))
+                violations.push(`${name}: word count (${wc}) exceeds budget (${mw})`);
+        }
+    }
+    for (const groupKey of ["VALIDATION", "VALIDATION_RULES"]) {
+        for (const ve of Object.values(schema[groupKey] ?? {})) {
+            if (!isMapping(ve))
+                continue;
+            const rule = String(ve.rule ?? "");
+            if (ve.severity !== "error")
+                continue;
+            if (rule.includes("unique") && rule.includes("number")) {
+                for (const [key, val] of Object.entries(data)) {
+                    if (Array.isArray(val)) {
+                        const nums = val
+                            .filter((e) => isMapping(e) && "number" in e)
+                            .map((e) => e.number);
+                        if (nums.length > 0) {
+                            if (nums.length !== new Set(nums).size) {
+                                violations.push(`${name}: duplicate numbers in '${key}'`);
+                            }
+                            const direction = expectedSequenceOrder(name, key);
+                            if (!sequenceInOrder(nums, direction)) {
+                                violations.push(`${name}: '${key}' not in ${direction} order`);
+                            }
+                        }
+                    }
+                }
+            }
+            else if (rule === "closure_consistency") {
+                const header = isMapping(data.header) ? data.header : {};
+                const status = data.status ?? header.status;
+                if (typeof status === "string" && status === "closed") {
+                    for (const field of ["closed_at", "final_value", "target_ref", "reason"]) {
+                        let val = data[field];
+                        if (val === null || val === undefined)
+                            val = header[field];
+                        if (val === null || val === undefined || (typeof val === "string" && !val.trim())) {
+                            violations.push(`${name}: closure field '${field}' is required when status is 'closed'`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return violations;
+}
+export { loadYamlMapping, schemasDirDefault };
+//# sourceMappingURL=violations.js.map

package/dist/hooks/validateArtifact/violations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"violations.js","sourceRoot":"","sources":["../../../src/hooks/validateArtifact/violations.ts"],"names":[],"mappings":"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"}

package/dist/migrate/v2HandoffManifest.js

@@ -0,0 +1,455 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isLifecycleOwnershipStateDirectory } from "../runtime/lifecycleOwnershipJournal.js";
+import { AGENTERA_PROFILE_DIR_ENV, PROFILERA_PROFILE_DIR_ENV, resolveProfileDirOverride, } from "../core/envPaths.js";
+import { expanduser, isFile, pathExists, resolvePath } from "../core/paths.js";
+import { opencodeConfigDir } from "../setup/opencode.js";
+import { doctorRoots, loadSuiteVersion } from "../upgrade/appModel.js";
+import { MANAGED_APP_CONTENT_ROOT_ENTRIES } from "../upgrade/appContentRefresh.js";
+import { AGENTERA_USER_STATE_NAMES, ROOT_USER_STATE_DIR_NAMES, ROOT_USER_STATE_FILE_NAMES, } from "../upgrade/doctor.js";
+/** Contract authority: references/cli/v3-handoff-manifest.schema.yaml */
+export const V2_HANDOFF_MANIFEST_SCHEMA_REL = "references/cli/v3-handoff-manifest.schema.yaml";
+export const V2_HANDOFF_MANIFEST_FILENAME = "v3-handoff.json";
+export const V2_HANDOFF_SCHEMA_VERSION = "agentera.v3_handoff_manifest.v1";
+export const READER_PREFLIGHT_BUDGET_MS = 100;
+export const USER_DATA_CATALOG_DIRS = [
+    "benchmarks",
+    "intermediate",
+    "sessions",
+    "history",
+    "corpus",
+];
+export const PROFILE_FILE_MEMBERS = ["PROFILE.md", "USAGE.md"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asNonEmptyString(value, field) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function parseDirectoryEntry(raw) {
+    const id = asNonEmptyString(raw.id, "user_data_inventory.id");
+    if (!USER_DATA_CATALOG_DIRS.includes(id)) {
+        throw new Error(`user_data_inventory id ${id} is not in the catalog`);
+    }
+    if (raw.kind !== "directory") {
+        throw new Error(`user_data_inventory entry ${id} must have kind=directory`);
+    }
+    if (typeof raw.exists !== "boolean") {
+        throw new Error(`user_data_inventory entry ${id} must have boolean exists`);
+    }
+    return {
+        id: id,
+        relative_path: asNonEmptyString(raw.relative_path, `user_data_inventory.${id}.relative_path`),
+        kind: "directory",
+        exists: raw.exists,
+    };
+}
+function parseProfileFilesEntry(raw) {
+    if (raw.id !== "profile_files") {
+        throw new Error("profile_files entry must have id=profile_files");
+    }
+    if (raw.kind !== "profile_files") {
+        throw new Error("profile_files entry must have kind=profile_files");
+    }
+    if (!Array.isArray(raw.members)) {
+        throw new Error("profile_files entry must have members array");
+    }
+    const members = raw.members.map((member, index) => {
+        if (!isRecord(member)) {
+            throw new Error(`profile_files.members[${index}] must be an object`);
+        }
+        if (member.kind !== "file") {
+            throw new Error(`profile_files.members[${index}] must have kind=file`);
+        }
+        if (typeof member.exists !== "boolean") {
+            throw new Error(`profile_files.members[${index}] must have boolean exists`);
+        }
+        return {
+            relative_path: asNonEmptyString(member.relative_path, `profile_files.members[${index}].relative_path`),
+            kind: "file",
+            exists: member.exists,
+        };
+    });
+    return { id: "profile_files", kind: "profile_files", members };
+}
+function parseUserDataInventory(raw) {
+    if (!Array.isArray(raw) || raw.length < 6) {
+        throw new Error("user_data_inventory must be an array with at least six entries");
+    }
+    const entries = raw.map((item, index) => {
+        if (!isRecord(item)) {
+            throw new Error(`user_data_inventory[${index}] must be an object`);
+        }
+        if (item.kind === "profile_files") {
+            return parseProfileFilesEntry(item);
+        }
+        return parseDirectoryEntry(item);
+    });
+    const ids = new Set(entries.map((entry) => entry.id));
+    for (const id of [...USER_DATA_CATALOG_DIRS, "profile_files"]) {
+        if (!ids.has(id)) {
+            throw new Error(`user_data_inventory missing catalog id ${id}`);
+        }
+    }
+    return entries;
+}
+export function parseV2HandoffManifest(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("manifest must be a JSON object");
+    }
+    const schemaVersion = asNonEmptyString(raw.schema_version, "schema_version");
+    if (schemaVersion !== V2_HANDOFF_SCHEMA_VERSION) {
+        throw new Error(`schema_version must be ${V2_HANDOFF_SCHEMA_VERSION}`);
+    }
+    const writtenAt = asNonEmptyString(raw.written_at, "written_at");
+    if (Number.isNaN(Date.parse(writtenAt))) {
+        throw new Error("written_at must be an ISO-8601 UTC timestamp");
+    }
+    if (!Array.isArray(raw.runtime_adapters)) {
+        throw new Error("runtime_adapters must be an array");
+    }
+    const runtimeAdapters = raw.runtime_adapters.map((adapter, index) => asNonEmptyString(adapter, `runtime_adapters[${index}]`));
+    return {
+        schema_version: V2_HANDOFF_SCHEMA_VERSION,
+        written_at: writtenAt,
+        installed_v2_version: asNonEmptyString(raw.installed_v2_version, "installed_v2_version"),
+        app_home_path: asNonEmptyString(raw.app_home_path, "app_home_path"),
+        user_data_inventory: parseUserDataInventory(raw.user_data_inventory),
+        runtime_adapters: runtimeAdapters,
+    };
+}
+export function v2HandoffManifestPath(appHome) {
+    return path.join(resolvePath(appHome), V2_HANDOFF_MANIFEST_FILENAME);
+}
+export function readV2HandoffManifestFile(appHome) {
+    const manifestPath = v2HandoffManifestPath(appHome);
+    if (!isFile(manifestPath)) {
+        return null;
+    }
+    const started = performance.now();
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (exc) {
+        throw new Error(`failed to read ${V2_HANDOFF_MANIFEST_FILENAME}: ${exc.message}`);
+    }
+    const manifest = parseV2HandoffManifest(parsed);
+    const elapsedMs = performance.now() - started;
+    return { manifest, elapsedMs };
+}
+function agenteraUserStateDirIsRecognized(dir) {
+    if (!pathExists(dir) || !fs.statSync(dir).isDirectory()) {
+        return false;
+    }
+    for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const st = fs.statSync(full);
+        if (AGENTERA_USER_STATE_NAMES.has(entry) && st.isFile()) {
+            continue;
+        }
+        if ((entry === "optimize" || entry === "optimera") && st.isDirectory()) {
+            // "optimera" is the v2 stable legacy objective dir name; keep it
+            // recognized so v2->v3 migration preserves legacy objective state.
+            continue;
+        }
+        if (entry === "runtime-lifecycle" && isLifecycleOwnershipStateDirectory(full)) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function isPreservedUserStateEntry(appHome, entry) {
+    const full = path.join(appHome, entry);
+    if (!pathExists(full)) {
+        return false;
+    }
+    const st = fs.statSync(full);
+    if (ROOT_USER_STATE_FILE_NAMES.has(entry) && st.isFile()) {
+        return true;
+    }
+    if (ROOT_USER_STATE_DIR_NAMES.has(entry) && st.isDirectory()) {
+        return true;
+    }
+    if (entry === ".agentera" && agenteraUserStateDirIsRecognized(full)) {
+        return true;
+    }
+    if (USER_DATA_CATALOG_DIRS.includes(entry) &&
+        st.isDirectory()) {
+        return true;
+    }
+    return false;
+}
+function listPreservedTopLevelFromScan(appHome) {
+    if (!pathExists(appHome)) {
+        return [];
+    }
+    const preserved = [];
+    for (const entry of fs.readdirSync(appHome)) {
+        if (entry === "app" || entry === V2_HANDOFF_MANIFEST_FILENAME) {
+            continue;
+        }
+        if (isPreservedUserStateEntry(appHome, entry)) {
+            preserved.push(entry);
+        }
+    }
+    return preserved.sort();
+}
+function listPreservedAbsolutePathsFromScan(appHome) {
+    const preserved = [];
+    for (const entry of listPreservedTopLevelFromScan(appHome)) {
+        const full = path.join(appHome, entry);
+        preserved.push(full);
+        if (entry === ".agentera" && pathExists(full) && fs.statSync(full).isDirectory()) {
+            for (const name of AGENTERA_USER_STATE_NAMES) {
+                const nested = path.join(full, name);
+                if (isFile(nested)) {
+                    preserved.push(nested);
+                }
+            }
+        }
+    }
+    return preserved.sort();
+}
+function listPreservedTopLevelFromManifest(manifest) {
+    const preserved = new Set();
+    for (const entry of manifest.user_data_inventory) {
+        if (entry.kind === "directory" && entry.exists) {
+            preserved.add(entry.relative_path);
+        }
+        if (entry.kind === "profile_files") {
+            for (const member of entry.members) {
+                if (member.exists) {
+                    preserved.add(member.relative_path);
+                }
+            }
+        }
+    }
+    return [...preserved].sort();
+}
+function listPreservedAbsolutePathsFromManifest(manifest, appHome) {
+    const root = resolvePath(appHome);
+    const preserved = [];
+    for (const rel of listPreservedTopLevelFromManifest(manifest)) {
+        preserved.push(path.join(root, rel));
+    }
+    const agenteraDir = path.join(root, ".agentera");
+    if (pathExists(agenteraDir) && fs.statSync(agenteraDir).isDirectory()) {
+        preserved.push(agenteraDir);
+        for (const name of AGENTERA_USER_STATE_NAMES) {
+            const nested = path.join(agenteraDir, name);
+            if (isFile(nested)) {
+                preserved.push(nested);
+            }
+        }
+    }
+    return preserved.sort();
+}
+export function isManifestCatalogEntryPreserved(manifest, entry) {
+    for (const item of manifest.user_data_inventory) {
+        if (item.kind === "directory" && item.relative_path === entry) {
+            return item.exists;
+        }
+        if (item.kind === "profile_files") {
+            for (const member of item.members) {
+                if (member.relative_path === entry) {
+                    return member.exists;
+                }
+            }
+        }
+    }
+    if (entry === ".agentera") {
+        const agenteraDir = path.join(resolvePath(manifest.app_home_path), ".agentera");
+        return agenteraUserStateDirIsRecognized(agenteraDir);
+    }
+    return false;
+}
+function profileDirEnvVar(env) {
+    if (env[AGENTERA_PROFILE_DIR_ENV]) {
+        return AGENTERA_PROFILE_DIR_ENV;
+    }
+    if (env[PROFILERA_PROFILE_DIR_ENV]) {
+        return PROFILERA_PROFILE_DIR_ENV;
+    }
+    return null;
+}
+function opencodeConfigDirEnvVar(env) {
+    if (env.OPENCODE_CONFIG_DIR) {
+        return "OPENCODE_CONFIG_DIR";
+    }
+    if (env.XDG_CONFIG_HOME) {
+        return "XDG_CONFIG_HOME";
+    }
+    return null;
+}
+function listUserDataPathsAtRoot(root) {
+    const preserved = new Set([root]);
+    for (const dir of USER_DATA_CATALOG_DIRS) {
+        const full = path.join(root, dir);
+        if (pathExists(full) && fs.statSync(full).isDirectory()) {
+            preserved.add(full);
+        }
+    }
+    for (const file of PROFILE_FILE_MEMBERS) {
+        const full = path.join(root, file);
+        if (isFile(full)) {
+            preserved.add(full);
+        }
+    }
+    return [...preserved].sort();
+}
+function opencodeConfigDirHasArtifacts(configDir) {
+    if (isFile(path.join(configDir, "plugins", "agentera.js"))) {
+        return true;
+    }
+    const agentsDir = path.join(configDir, "agents");
+    if (pathExists(agentsDir) && fs.statSync(agentsDir).isDirectory()) {
+        if (fs.readdirSync(agentsDir).some((name) => isFile(path.join(agentsDir, name)))) {
+            return true;
+        }
+    }
+    return pathExists(path.join(configDir, "skills", "agentera"));
+}
+function listOpencodeConfigCatalog(configDir) {
+    const preserved = new Set([configDir]);
+    for (const rel of ["plugins/agentera.js", "agents", "commands", "skills"]) {
+        const full = path.join(configDir, rel);
+        if (pathExists(full)) {
+            preserved.add(full);
+        }
+    }
+    return [...preserved].sort();
+}
+export function buildExternalHandoffCatalog(appHome, opts) {
+    if (!opts?.env) {
+        return [];
+    }
+    const env = opts.env;
+    const home = resolvePath(opts.home ?? appHome);
+    const resolvedAppHome = resolvePath(appHome);
+    const catalog = [];
+    const profileEnvVar = profileDirEnvVar(env);
+    const profileOverride = resolveProfileDirOverride(env);
+    if (profileEnvVar && profileOverride) {
+        const profileDir = resolvePath(expanduser(profileOverride));
+        if (profileDir !== resolvedAppHome) {
+            catalog.push({
+                surface: "custom_profile_dir",
+                root: profileDir,
+                envVar: profileEnvVar,
+                entries: listUserDataPathsAtRoot(profileDir),
+            });
+        }
+    }
+    const opencodeEnvVar = opencodeConfigDirEnvVar(env);
+    if (opencodeEnvVar) {
+        const configDir = opencodeConfigDir(home, env);
+        const defaultDir = resolvePath(path.join(home, ".config", "opencode"));
+        if (configDir !== defaultDir && opencodeConfigDirHasArtifacts(configDir)) {
+            catalog.push({
+                surface: "opencode_runtime_config_dir",
+                root: configDir,
+                envVar: opencodeEnvVar,
+                entries: listOpencodeConfigCatalog(configDir),
+            });
+        }
+    }
+    return catalog;
+}
+function mergePreservedAbsolutePaths(base, handoffCatalog) {
+    const merged = new Set(base);
+    for (const entry of handoffCatalog) {
+        for (const absolutePath of entry.entries) {
+            merged.add(absolutePath);
+        }
+    }
+    return [...merged].sort();
+}
+export function handoffCatalogMessage(entry) {
+    if (entry.surface === "custom_profile_dir") {
+        return `custom profile dir (${entry.envVar}=${entry.root}) cataloged for v2→v3 handoff`;
+    }
+    return `opencode runtime config dir (${entry.envVar} → ${entry.root}) cataloged for v2→v3 handoff`;
+}
+export function resolveMigrationUserStatePreflight(appHome, opts) {
+    const resolvedHome = resolvePath(appHome);
+    const handoffCatalog = buildExternalHandoffCatalog(resolvedHome, opts);
+    const manifestRead = readV2HandoffManifestFile(resolvedHome);
+    if (manifestRead) {
+        return {
+            source: "manifest",
+            elapsedMs: manifestRead.elapsedMs,
+            manifest: manifestRead.manifest,
+            preservedTopLevel: listPreservedTopLevelFromManifest(manifestRead.manifest),
+            preservedAbsolutePaths: mergePreservedAbsolutePaths(listPreservedAbsolutePathsFromManifest(manifestRead.manifest, resolvedHome), handoffCatalog),
+            handoffCatalog,
+        };
+    }
+    const started = performance.now();
+    const preservedTopLevel = listPreservedTopLevelFromScan(resolvedHome);
+    const preservedAbsolutePaths = mergePreservedAbsolutePaths(listPreservedAbsolutePathsFromScan(resolvedHome), handoffCatalog);
+    return {
+        source: "scan",
+        elapsedMs: performance.now() - started,
+        manifest: null,
+        preservedTopLevel,
+        preservedAbsolutePaths,
+        handoffCatalog,
+    };
+}
+export function appHomeHasUnrecognizedEntriesWithPreflight(appHome, preflight) {
+    if (!pathExists(appHome)) {
+        return [];
+    }
+    const unknown = [];
+    for (const entry of fs.readdirSync(appHome)) {
+        if (entry === "app" || entry === V2_HANDOFF_MANIFEST_FILENAME) {
+            continue;
+        }
+        if (MANAGED_APP_CONTENT_ROOT_ENTRIES.has(entry)) {
+            continue;
+        }
+        if (preflight.source === "manifest" && preflight.manifest) {
+            if (isManifestCatalogEntryPreserved(preflight.manifest, entry)) {
+                continue;
+            }
+        }
+        else if (isPreservedUserStateEntry(appHome, entry)) {
+            continue;
+        }
+        unknown.push(entry);
+    }
+    return unknown;
+}
+export function isV2HandoffManifestStale(manifest, ctx) {
+    if (resolvePath(manifest.app_home_path) !== resolvePath(ctx.appHome)) {
+        return true;
+    }
+    if (manifest.installed_v2_version !== ctx.installedVersion) {
+        return true;
+    }
+    const writtenAtMs = Date.parse(manifest.written_at);
+    const markerMs = ctx.bundleMarkerMtimeMs;
+    if (Number.isNaN(writtenAtMs) || Math.floor(writtenAtMs / 1000) < Math.floor(markerMs / 1000)) {
+        return true;
+    }
+    return false;
+}
+export function bundleMarkerFreshnessContext(appHome, sourceRoot) {
+    const roots = doctorRoots(appHome);
+    const markerPath = path.join(roots.activeBundleRoot, ".agentera-bundle.json");
+    if (!isFile(markerPath)) {
+        return null;
+    }
+    const installedVersion = loadSuiteVersion(roots.activeBundleRoot) ?? loadSuiteVersion(sourceRoot) ?? "unknown";
+    return {
+        appHome: resolvePath(appHome),
+        installedVersion,
+        bundleMarkerMtimeMs: fs.statSync(markerPath).mtimeMs,
+    };
+}
+//# sourceMappingURL=v2HandoffManifest.js.map