agentera 3.0.0-dev.51 → 3.0.0-dev.69

package/dist/cli/commands/prime/collectOrientationState.js

@@ -12,7 +12,7 @@ import { v1MigrationSummary } from "./v1Migration.js";
 import { diagnoseCanonicalSkill } from "../../../setup/sharedSkill.js";
 import { collectEntityOrientation } from "./collectEntityOrientation.js";
 import { acquireProfile } from "../../profileAcquisition.js";
-import { fullEntityUpgradeCommand } from "../../../upgrade/upgradeCommands.js";
+import { fullEntityUpgradeCommand, fullEntityUpgradePreviewCommand } from "../../../upgrade/upgradeCommands.js";
 import { classifyEntityCutoverProject } from "../../../state/entityMigrationPreview.js";
 import { preCutoverCommand } from "../../preCutoverCommand.js";
 const EMPTY_SCHEMAS = Object.freeze({});
@@ -22,7 +22,14 @@ function stateCutover(project, sourceRoot) {
         if (projectState === "v3") {
             return { status: "complete", project_state: "v3", recovery_command: null };
         }
-        return { status: "required", project_state: projectState, recovery_command: fullEntityUpgradeCommand(project) };
+        if (projectState === "fresh_uninitialized") {
+            return { status: "fresh_uninitialized", project_state: projectState, recovery_command: null };
+        }
+        return {
+            status: "required",
+            project_state: projectState,
+            recovery_command: projectState === "legacy" ? fullEntityUpgradeCommand(project) : fullEntityUpgradePreviewCommand(project),
+        };
     }
     catch {
         return { status: "invalid_lifecycle", project_state: "invalid_lifecycle", recovery_command: preCutoverCommand("check validate state --format json") };
@@ -99,13 +106,13 @@ export function collectOrientationState(opts) {
     const readiness = selectStatusReadiness(plan, health, objective, todoItems, decision, savedContext, entity.todoReadiness);
     const reconciliationReadiness = entity.todoReconciliation?.status === "action_required"
         ? withRecommended(readiness, {
-            object: entity.todoReconciliation.state === "unsafe_inactive" ? "Replan unsafe TODO activation correction" : entity.todoReconciliation.state === "inactive" ? "Activate TODO reconciliation" : "Repair TODO reconciliation",
-            capability: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : "build",
+            object: entity.todoReconciliation.state === "unsafe_inactive" ? "Correct unsafe TODO ownership" : entity.todoReconciliation.state === "inactive" ? "Activate TODO reconciliation" : "Repair TODO reconciliation",
+            capability: "build",
             reason: entity.todoReconciliation.recovery_command,
-            phase: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : entity.todoReconciliation.state === "invalid_lifecycle" ? "audit" : "build",
+            phase: entity.todoReconciliation.state === "unsafe_inactive" ? "build" : entity.todoReconciliation.state === "invalid_lifecycle" ? "audit" : "build",
         })
         : readiness;
-    const nextAction = cutover.status !== "complete"
+    const nextAction = cutover.status === "required" || cutover.status === "invalid_lifecycle"
         ? withRecommended(readiness, {
             object: "Complete Agentera entity-state cutover",
             capability: "status",

package/dist/cli/commands/prime/orientationOutput.js

@@ -32,8 +32,7 @@ function nextActionEntry(action) {
  *  and `alternatives` carries the cascade branches the early-return model
  *  would have skipped, each with the same `{object, capability, reason, phase}`
  *  shape. */
-function nextActionPayload(state) {
-    const { recommended, alternatives } = state.next_action;
+function nextActionPayload({ recommended, alternatives }) {
     return {
         ...nextActionEntry(recommended),
         alternatives: alternatives.map(nextActionEntry),
@@ -163,7 +162,7 @@ export function buildOrientationJsonPayload(state, command, options = {}) {
         attention: projectPublicOrientationAttention(state).map((item) => truncateCodePoints(item, 200, "…")),
         decision_attention: state.decision_attention,
         history: state.history,
-        next_action: nextActionPayload(state),
+        next_action: nextActionPayload(state.next_action),
         startup,
         orchestration_context: bespoke.orchestration_context,
         closeout_context: bespoke.closeout_context,
@@ -192,6 +191,29 @@ export function buildStatusContextState(state, _command = "prime", _options = {}
     const firstPending = plan.first_pending && typeof plan.first_pending === "object" && !Array.isArray(plan.first_pending)
         ? plan.first_pending
         : null;
+    const risks = todoReconciliation?.risks;
+    const unsafeDetailOmitted = todoReconciliation?.state === "unsafe_inactive"
+        && Boolean(risks && typeof risks === "object" && !Array.isArray(risks) && Number(risks.omitted_count) > 0);
+    const recovery = unsafeDetailOmitted && typeof todoReconciliation.recovery_command === "string"
+        ? todoReconciliation.recovery_command
+        : null;
+    const todoAttention = unsafeDetailOmitted
+        ? new Set(state.todo_items.map((item) => `${String(item.severity)}: TODO: ${String(item.text)}`))
+        : new Set();
+    const attention = projectPublicOrientationAttention(state)
+        .flatMap((item) => item === `action-required: TODO reconciliation is unsafe inactive; ${recovery}`
+        ? ["action-required: TODO reconciliation is unsafe inactive; see capability_context.startup.todo_reconciliation"]
+        : todoAttention.has(item) ? [] : [item])
+        .map((item) => truncateCodePoints(item, 200, "…"));
+    const redactRecovery = (action) => recovery !== null && action.reason === recovery
+        ? { ...action, reason: "See capability_context.startup.todo_reconciliation for recovery." }
+        : action;
+    const nextAction = {
+        recommended: redactRecovery(state.next_action.recommended),
+        alternatives: state.next_action.alternatives
+            .filter((action) => !unsafeDetailOmitted || action.artifact !== "todo")
+            .map(redactRecovery),
+    };
     return {
         outcome: startup.outcome,
         mode: state.mode,
@@ -231,8 +253,8 @@ export function buildStatusContextState(state, _command = "prime", _options = {}
         progress: { exists: state.progress.exists, status: state.progress.status ?? null, latest: state.progress.latest ?? null },
         objective: { exists: state.objective.exists, active: state.objective.active ?? false, title: state.objective.title ?? null },
         state_presence: state.state_presence,
-        attention: projectPublicOrientationAttention(state).map((item) => truncateCodePoints(item, 200, "…")),
-        next_action: nextActionPayload(state),
+        attention,
+        next_action: nextActionPayload(nextAction),
     };
 }
 export function emitPrime(command, payload, format, fieldsArg, out, err, options = {}) {

package/dist/cli/commands/state/write.js

@@ -280,7 +280,10 @@ function parseWrite(artifactRaw, argv) {
             example: exampleFor(artifact, verb),
         });
     const selectorFields = new Set(spec.fields.filter((field) => spec.selectors.includes(field.flag)).map((field) => field.field));
-    if (spec.inputRoot && Object.keys(values).some((field) => !selectorFields.has(field)))
+    const correctionApplyFields = artifact === "todo" && verb === "correct-owners"
+        ? new Set(["effect_sha256", "confirmed"])
+        : new Set();
+    if (spec.inputRoot && Object.keys(values).some((field) => !selectorFields.has(field) && !correctionApplyFields.has(field)))
         invalid({
             class: "mutually_exclusive",
             message: `--input cannot be combined with field flags for ${artifact} ${verb}`,

package/dist/cli/dispatch/index.js

@@ -63,7 +63,7 @@ export function main(argv, io = {}) {
     // must report its source-checkout boundary before project migration checks.
     const sourceOnlyReferenceValidation = args[0] === "check" && args[1] === "validate" && ["retained-references", "activation-conjunction"].includes(args[2] ?? "");
     if (!sourceOnlyReferenceValidation && requiresCompletedEntityCutover(args)) {
-        const failure = enforceCompletedEntityCutover(migrationProject(args), requestedMigrationFailureFormat(args), io);
+        const failure = enforceCompletedEntityCutover(migrationProject(args), requestedMigrationFailureFormat(args), io, args);
         if (failure !== null)
             return failure;
     }

package/dist/cli/help.js

@@ -204,6 +204,7 @@ export function printStateHelp(sub) {
         return [
             ...recordFamilyReadSection("todo"),
             "       agentera state todo activate|repair --dry-run|--effect-sha256 SHA256 --yes --format json",
+            "       agentera state todo correct-owners --input OWNER_MAPPING.yaml --dry-run|--effect-sha256 SHA256 --yes --format json",
             "       agentera state todo create --input TODO.yaml --format json",
             "       agentera state todo update --id ID --input TODO-PATCH.yaml --format json",
             "       agentera state todo set-severity --id ID --severity LEVEL --reason TEXT --date YYYY-MM-DD --format json",

package/dist/cli/migrationRequired.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { emitStructured } from "./structured.js";
-import { detectStateMode } from "../state/stateMode.js";
-import { fullEntityUpgradeCommand } from "../upgrade/upgradeCommands.js";
+import { classifyProjectState, detectStateMode } from "../state/stateMode.js";
+import { commandText, fullEntityUpgradeCommand, fullEntityUpgradePreviewCommand } from "../upgrade/upgradeCommands.js";
 import { preCutoverCommand } from "./preCutoverCommand.js";
 function value(argv, flag) {
     const equals = argv.find((arg) => typeof arg === "string" && arg.startsWith(`${flag}=`));
@@ -46,8 +46,19 @@ export function migrationProject(argv, fallback = process.cwd()) {
         candidate = parent;
     }
 }
+function permitsFreshPlanInitialization(argv) {
+    const [command, subcommand, verb] = argv;
+    return command === "state" && subcommand === "plan" && verb === "create"
+        || command === "prime" && value(argv, "--context") === "plan";
+}
+function freshPlanCreateCommand(project) {
+    return commandText([
+        "npx", "-y", "agentera@next", "state", "plan", "create", "--project", project,
+        "--input", "PLAN.yaml", "--format", "json",
+    ]);
+}
 /** Read-only cutover gate. It only inspects the durable marker and emits a failure. */
-export function enforceCompletedEntityCutover(projectRoot, format, io = {}) {
+export function enforceCompletedEntityCutover(projectRoot, format, io = {}, argv = []) {
     const project = path.resolve(projectRoot);
     let mode;
     try {
@@ -68,13 +79,37 @@ export function enforceCompletedEntityCutover(projectRoot, format, io = {}) {
     }
     if (mode === "entities")
         return null;
-    const recovery = fullEntityUpgradeCommand(project);
+    const classification = classifyProjectState(project);
+    if (classification.state === "fresh_uninitialized") {
+        if (permitsFreshPlanInitialization(argv))
+            return null;
+        const recovery = freshPlanCreateCommand(project);
+        const envelope = {
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "fresh_initialization_required",
+                message: "Fresh project state is initialized only by state plan create; no other state writer can create entity authority.",
+                project,
+                recovery,
+            },
+        };
+        if (format === "json" || format === "yaml")
+            emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+        else
+            (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+        return 1;
+    }
+    const legacy = classification.state === "legacy";
+    const recovery = legacy ? fullEntityUpgradeCommand(project) : fullEntityUpgradePreviewCommand(project);
     const envelope = {
         schemaVersion: "agentera.stateFailure.v1",
         status: "fail",
         error: {
             class: "migration_required",
-            message: "This command requires the completed entity-state cutover; legacy aggregates remain migration input only.",
+            message: legacy
+                ? "This command requires the completed entity-state cutover; legacy aggregates remain migration input only."
+                : `This command cannot adopt marker-absent ${classification.state} Agentera state; inspect it with the read-only recovery command before any mutation.`,
             project,
             recovery,
         },

package/dist/registries/activationTuples.js

@@ -76,6 +76,7 @@ const rawTuples = JSON.parse(decodedCatalog.slice(decodedCatalog.indexOf("[", 2)
 const addedTuples = [
     { class: "state", surface_id: "write:plan.replace", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "plan.replace", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "state", surface_id: "write:todo.activate", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "todo.activate", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
+    { class: "state", surface_id: "write:todo.correct-owners", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "todo.correct-owners", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "state", surface_id: "write:todo.repair", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "todo.repair", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "package", surface_id: "emitted:packages/cli/src/cli/commands/doctor.ts", owner_path: "packages/cli/src/registries/packageRegistry.ts", owner_symbol_or_selector: "loadRegistry", owner_selector: "packages/cli/src/cli/commands/doctor.ts", semantic_selector_if_any: JSON.stringify({ path: "packages/cli/src/cli/commands/doctor.ts", selector: null, format: null, classification: null, reason: "Doctor project-state signals publish bounded reconciliation preview and apply guidance." }), canonical_correction: "pnpm -C packages/cli run verify:package" },
     { class: "package", surface_id: "emitted:packages/cli/src/state/todoReconciliationInspection.ts", owner_path: "packages/cli/src/registries/packageRegistry.ts", owner_symbol_or_selector: "loadRegistry", owner_selector: "packages/cli/src/state/todoReconciliationInspection.ts", semantic_selector_if_any: JSON.stringify({ path: "packages/cli/src/state/todoReconciliationInspection.ts", selector: null, format: null, classification: null, reason: "TODO reconciliation inspection publishes bounded preview and effect-bound apply guidance." }), canonical_correction: "pnpm -C packages/cli run verify:package" },
@@ -95,11 +96,11 @@ export const ACTIVATION_TUPLE_AUTHORITY = Object.freeze({
         capability: { count: 12, sha256: "892e6e5e2a57b41064bc44fa2946453225f1b1195aff77aad05365fd0a1071c2" },
         runtime: { count: 81, sha256: "99b2abff3ebff889b54b1781c563ab4b32609a479c4e90d6aad854f48fba7edc" },
         reference: { count: 22, sha256: "243fd3c317553f8924c56a52c61af90ccf2793b7b0018af1373b73c69b6c3afb" },
-        state: { count: 37, sha256: "210bd831c5d62beac149efd888ee4a99af49a9469cf373031f8db9893904d0c1" },
+        state: { count: 38, sha256: "697de8dcd13ac521124c35058ba222aa5cb6cae546f00bb54652ceaca4b662aa" },
         package: { count: 66, sha256: "83e6971af7f7564e42369aaccc445b32a0793bfffade843d149b6abd4fd3dbbc" },
         bootstrap: { count: 34, sha256: "9a7dd7e27110d85cf5c08835fdd8f08119e75579858e63bc6d396c733961d0bc" },
     },
-    total: { count: 279, sha256: "c2d7a66bc9af04a5511348825995317a5968357c6cacbfd87eb2cc4fbe77156c" },
+    total: { count: 280, sha256: "cd9396b45a82383e2f58da851f00061fa4c23c504ba9f41cf9fd7c7c39b0b092" },
 });
 export function canonicalTupleJson(value) { return JSON.stringify(value); }
 export function digestCanonicalTuples(values) {

package/dist/registries/packagePublication.js

@@ -53,11 +53,11 @@ export const ACTIVATION_CENSUS_AUTHORITY = deepFreeze({
         capability: { count: 12, sha256: "007e1157a892fec54182b1803aeaa442cf8e2e332e6a055c3bd020e2b0731867" },
         runtime: { count: 81, sha256: "03fe600a3a27f05daf0d1b59c16b00bedc354a13c70ea60be0b457175fdf743c" },
         reference: { count: 22, sha256: "2b48c82bb7ee10388d9ebb4fa7ea3743ea82a7e9aaedfcd5a858eeedb9d891ae" },
-        state: { count: 37, sha256: "ca87acdb0fda04ba46a52163fc30ec6578c077e61fcb64597f861a36fdce1dc4" },
+        state: { count: 38, sha256: "7ab0dd6ef1b1b1ce66bd9ea94d1de3d542528233e928a44102e289bf12416681" },
         package: { count: 66, sha256: "3548af7e84151c90690a6eb3d1cb6c7847f39b290161ecab599d8cb1bf0d2cb0" },
         bootstrap: { count: 34, sha256: "71c2038744e2518a6adb722acbb5f9352bddfb5d1c92eeb0e347297ef2ca2f1e" },
     },
-    total: { count: 279, sha256: "b92cd469f858e9584682d05b4d9bb03c2fc4b905f3485475723786c0a978c138" },
+    total: { count: 280, sha256: "051ed9a57857a39e11ed8fb583bff9d2a67a306c5ab897a0ee829212468bc23a" },
 });
 /** Each dimension names the production contract it observes independently. */
 export const ACTIVATION_EVIDENCE_SOURCES = deepFreeze({
@@ -71,12 +71,13 @@ export const ACTIVATION_EVIDENCE_SOURCES = deepFreeze({
 });
 export const ACTIVATION_CHECK_IDS = Object.freeze(ACTIVATION_CLASSES.flatMap((classId) => ACTIVATION_DIMENSIONS.map((dimension) => `${classId}.${dimension}`)));
 export const SOURCE_GATE_IDS = [
-    "source", "stress", "performance", "package", "generated-overlap", "typecheck", "build",
+    "source", "stress", "performance", "capacity", "package", "generated-overlap", "typecheck", "build",
     "compact", "capability-contract", "activation-conjunction",
 ];
 export const SOURCE_DAG_PHASES = {
     batchA: ["generated-overlap", "stress", "typecheck"],
     performanceBarrier: ["performance"],
+    capacityBarrier: ["capacity"],
     barrierB: ["compact", "capability-contract", "activation-conjunction"],
     generatedOverlapOrigins: ["source", "package", "build", "generated-overlap"],
 };
@@ -84,6 +85,7 @@ const EXACT_COMMANDS = {
     source: ["pnpm", "-C", "packages/cli", "run", "test:source"],
     stress: ["pnpm", "-C", "packages/cli", "run", "test:stress"],
     performance: ["pnpm", "-C", "packages/cli", "run", "test:performance"],
+    capacity: ["pnpm", "-C", "packages/cli", "run", "test:capacity"],
     package: ["pnpm", "-C", "packages/cli", "run", "verify:package"],
     "generated-overlap": ["pnpm", "-C", "packages/cli", "run", "verify:generated-overlap"],
     typecheck: ["pnpm", "-C", "packages/cli", "run", "typecheck"],
@@ -133,11 +135,33 @@ export function validatePackagePublicationDocument(raw) {
     if (raw?.schemaVersion !== "agentera.packagePublication.v2")
         fail("schemaVersion is invalid");
     const source = raw?.qualification?.source;
+    const readiness = raw?.qualification?.readiness;
     const activation = source?.activationConjunction;
     if (!source || !activation || activation.gateIdentity !== "agentera.activationConjunction.v1")
         fail("source activation conjunction is missing or invalid");
+    if (!readiness
+        || readiness.schemaVersion !== "agentera.releaseReadiness.v1"
+        || readiness.component !== "release-readiness"
+        || readiness.adapter !== "development")
+        fail("release readiness authority is missing or invalid");
+    const readinessCommand = boundedText(readiness.command, "release readiness command", 320, /^node packages\/cli\/scripts\/release-readiness\.mjs development --candidate-dir DIR --target-version VERSION --source-commit COMMIT \[--metadata-commit COMMIT\] \[--json\]$/);
+    const readinessPhases = exactList(readiness.phases, ["source-readiness", "metadata-review", "candidate-readiness"], "release readiness phases");
+    if (!readiness.receipts
+        || Object.keys(readiness.receipts).sort().join("\0") !== "candidate\0source"
+        || readiness.receipts.source !== "source-receipt.json"
+        || readiness.receipts.candidate !== "candidate-receipt.json")
+        fail("release readiness receipts must name the governed source and candidate receipts");
+    const readinessReuse = boundedText(readiness.reuse, "release readiness reuse rule", 1200, /^[^\0\r\n]+$/);
+    const readinessMetadataReview = boundedText(readiness.metadataReview, "release readiness metadata review rule", 1200, /^[^\0\r\n]+$/);
+    const readinessOutcomes = exactList(readiness.outcomes, ["paused", "ready", "rejected"], "release readiness outcomes");
+    if (!readiness.exitCodes
+        || Object.keys(readiness.exitCodes).sort().join("\0") !== "paused\0ready\0rejected"
+        || readiness.exitCodes.paused !== 0
+        || readiness.exitCodes.ready !== 0
+        || readiness.exitCodes.rejected !== 1)
+        fail("release readiness exit codes must map paused and ready to 0 and rejected to 1");
     if (!Array.isArray(source.gates) || source.gates.length !== SOURCE_GATE_IDS.length)
-        fail("source gates must contain exactly ten entries");
+        fail(`source gates must contain exactly ${SOURCE_GATE_IDS.length} entries`);
     const sourceGates = source.gates.map((gate, index) => {
         const name = SOURCE_GATE_IDS[index];
         if (!gate || gate.name !== name)
@@ -152,9 +176,10 @@ export function validatePackagePublicationDocument(raw) {
     const dag = source.dag;
     const batchA = exactList(dag?.batchA, SOURCE_DAG_PHASES.batchA, "source batch A");
     const performanceBarrier = exactList(dag?.performanceBarrier, SOURCE_DAG_PHASES.performanceBarrier, "source performance barrier");
+    const capacityBarrier = exactList(dag?.capacityBarrier, SOURCE_DAG_PHASES.capacityBarrier, "source capacity barrier");
     const barrierB = exactList(dag?.barrierB, SOURCE_DAG_PHASES.barrierB, "source barrier B");
     const generatedOverlapOrigins = exactList(dag?.generatedOverlapOrigins, SOURCE_DAG_PHASES.generatedOverlapOrigins, "generated overlap origins");
-    const phases = [...batchA, ...performanceBarrier, ...barrierB];
+    const phases = [...batchA, ...performanceBarrier, ...capacityBarrier, ...barrierB];
     if (phases.length !== new Set(phases).size)
         fail("source execution phases must be disjoint");
     const scheduled = new Set([...phases, ...generatedOverlapOrigins]);
@@ -211,12 +236,31 @@ export function validatePackagePublicationDocument(raw) {
     return {
         sourceGates,
         sourceDag: {
-            batchA, performanceBarrier, barrierB, generatedOverlapOrigins,
+            batchA, performanceBarrier, capacityBarrier, barrierB, generatedOverlapOrigins,
             overlapCleanupMarginMs: positiveInteger(dag.overlapCleanupMarginMs, "overlap cleanup margin", 60_000),
             overlapParentReconciliationMarginMs: positiveInteger(dag.overlapParentReconciliationMarginMs, "parent reconciliation margin", 60_000),
             minimumExecutionWindowMs,
         },
-        sourceQualificationMs: positiveInteger(raw?.benchmark?.timeouts?.sourceQualificationMs, "source qualification timeout", 900_000),
+        sourceQualificationMs: positiveInteger(raw?.benchmark?.timeouts?.sourceQualificationMs, "source qualification timeout", 2_400_000),
+        readiness: {
+            schemaVersion: readiness.schemaVersion,
+            component: readiness.component,
+            adapter: readiness.adapter,
+            command: readinessCommand,
+            phases: readinessPhases,
+            receipts: {
+                source: readiness.receipts.source,
+                candidate: readiness.receipts.candidate,
+            },
+            reuse: readinessReuse,
+            metadataReview: readinessMetadataReview,
+            outcomes: readinessOutcomes,
+            exitCodes: {
+                paused: readiness.exitCodes.paused,
+                ready: readiness.exitCodes.ready,
+                rejected: readiness.exitCodes.rejected,
+            },
+        },
         activationConjunction: {
             gateIdentity: activation.gateIdentity, classes, dimensions, checkIds, bounds, owners,
             census: { algorithm: ACTIVATION_CENSUS_AUTHORITY.algorithm, classes: censusClasses, total: censusTotal },

package/dist/state/entityMigrationPreview.js

@@ -22,18 +22,12 @@ import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
 import { legacySummaryRecord } from "./legacySummaryRecord.js";
 import { applyCausalBlockers } from "./entityMigrationCausality.js";
 import { todoMigrationObservations, todoReconciliationMigrationPlan } from "./entityMigrationTodo.js";
-import { detectStateMode } from "./stateMode.js";
+import { classifyProjectState } from "./stateMode.js";
 import { TODO_RECONCILIATION_ACTIVATION_PATH } from "./todoReconciliationActivation.js";
 import { projectPathIsStable as migrationPathIsStable, readProjectFileSnapshot, resolveProjectDescriptorPath, snapshotProjectPath as snapshotMigrationPath, } from "./safeProjectFile.js";
 export function classifyEntityCutoverProject(project, sourceRoot) {
-    if (detectStateMode(project, sourceRoot) === "entities")
-        return "v3";
-    const stateRoot = path.join(project, ".agentera");
-    const aggregateNames = ["plan.yaml", "progress.yaml", "decisions.yaml", "health.yaml"];
-    const aggregateCount = aggregateNames.filter((name) => fs.existsSync(path.join(stateRoot, name))).length;
-    if (!fs.existsSync(stateRoot) || aggregateCount === 0 && !fs.existsSync(path.join(stateRoot, "entities")))
-        return "clean";
-    return fs.existsSync(path.join(stateRoot, "entities")) || aggregateCount === 1 ? "partial" : "v2";
+    const state = classifyProjectState(project, sourceRoot).state;
+    return state === "entities" ? "v3" : state;
 }
 export const ENTITY_MIGRATION_PREVIEW_MAX_OUTPUT_BYTES = 32_768;
 const DEFAULT_LIMIT = 100;

package/dist/state/entityPublicationContext.js

@@ -245,6 +245,14 @@ function publicationConflict(markerPath) {
         example: `restore the exact '${markerPath}' marker selected at command start and retry`,
     });
 }
+function initializationConflict(markerPath) {
+    reject({
+        class: "conflict",
+        message: `state mode marker '${markerPath}' appeared during fresh plan initialization`,
+        syntax: "agentera state plan create --input PLAN.yaml --format json",
+        example: "remove no files; inspect the competing state publication and retry",
+    });
+}
 /**
  * Binds mutations to a validated project and exact entity-mode marker. Every
  * pathname and byte identity is checked at declared boundaries. Publication
@@ -264,14 +272,24 @@ export class EntityPublicationContext {
         this.validatedRoot = root;
         this.markerPath = markerPath;
         const markerAbsolute = path.join(root.path, ...safeSegments(markerPath, "state mode marker"));
-        this.marker = readStableFile(markerAbsolute, `state mode marker '${markerPath}'`);
-        if (!this.marker.bytes.equals(expectedBytes))
-            publicationConflict(markerPath);
+        if (expectedBytes === null) {
+            if (readFileIfPresent(markerAbsolute, `state mode marker '${markerPath}'`))
+                initializationConflict(markerPath);
+            this.marker = null;
+        }
+        else {
+            this.marker = readStableFile(markerAbsolute, `state mode marker '${markerPath}'`);
+            if (!this.marker.bytes.equals(expectedBytes))
+                publicationConflict(markerPath);
+        }
         this.assertValid();
     }
     static open(root, markerPath, expectedBytes) {
         return new EntityPublicationContext(root, markerPath, expectedBytes);
     }
+    static beginInitialization(root, markerPath) {
+        return new EntityPublicationContext(root, markerPath, null);
+    }
     pinnedPath(relativePath = "") {
         if (this.closed)
             throw new Error("entity publication context is closed");
@@ -283,6 +301,17 @@ export class EntityPublicationContext {
         if (this.closed)
             throw new Error("entity publication context is closed");
         assertValidatedProjectRoot(this.validatedRoot);
+        if (this.marker === null) {
+            try {
+                if (readFileIfPresent(path.join(this.projectRoot, ...safeSegments(this.markerPath, "state mode marker")), `state mode marker '${this.markerPath}'`)) {
+                    initializationConflict(this.markerPath);
+                }
+            }
+            catch {
+                initializationConflict(this.markerPath);
+            }
+            return;
+        }
         let current;
         try {
             current = readStableFile(this.marker.absolute, `state mode marker '${this.markerPath}'`);
@@ -294,9 +323,25 @@ export class EntityPublicationContext {
             publicationConflict(this.markerPath);
     }
     publishImmutable(relativeTarget, bytes) {
+        return this.publishImmutableInternal(relativeTarget, bytes, false);
+    }
+    isInitializing() {
+        return this.marker === null;
+    }
+    publishStateMarker(bytes) {
+        if (this.marker !== null)
+            throw new Error("entity state marker is already active");
+        const published = this.publishImmutableInternal(this.markerPath, bytes, true);
+        if (!published)
+            initializationConflict(this.markerPath);
+        return published;
+    }
+    publishImmutableInternal(relativeTarget, bytes, activateMarker) {
         const segments = safeSegments(relativeTarget, "immutable entity target");
         if (segments.length < 2)
             throw new Error(`unsafe immutable entity target '${relativeTarget}'`);
+        if (activateMarker && relativeTarget !== this.markerPath)
+            throw new Error("only the state mode marker can activate fresh entity state");
         const directories = [];
         const target = path.join(this.projectRoot, ...segments);
         let stage;
@@ -338,11 +383,15 @@ export class EntityPublicationContext {
                 throw new ExactReplacementConflictError(`immutable entity target '${relativeTarget}' changed at its publication boundary`);
             }
             publicationOwned = true;
+            if (activateMarker)
+                this.marker = published;
             this.assertBoundary(directories, published, [stage]);
             removeExactFile(stage);
             stage = undefined;
             syncDirectory(directory);
             published = readStableFile(target, `published entity '${relativeTarget}'`);
+            if (activateMarker)
+                this.marker = published;
             this.assertBoundary(directories, published);
             for (const entry of directories.filter(({ created }) => created)) {
                 this.createdDirectories.set(relativeDisplay(this.projectRoot, entry.absolute), entry);
@@ -350,6 +399,8 @@ export class EntityPublicationContext {
             return publishedIdentity(published);
         }
         catch (error) {
+            if (activateMarker)
+                this.marker = null;
             if (publicationOwned && published) {
                 if (stage) {
                     try {
@@ -434,6 +485,8 @@ export class EntityPublicationContext {
             return "identity_mismatch";
         fs.unlinkSync(target);
         syncDirectory(directory);
+        if (relativeTarget === this.markerPath)
+            this.marker = null;
         this.removeAttemptDirectories();
         return "removed";
     }

package/dist/state/planEntities.js

@@ -6,8 +6,9 @@ import { dumpYamlMapping } from "../core/yaml.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { StateRetrievalFailure } from "./directRetrieval.js";
 import { allocateEntityId, canonicalEntityEnvelopeBytes, entityExactGetMaxBytes, exactDiscoveredEntityBytes, publishEntity, replaceEntity, replaceEntityUnderLock, validateEntityDiscovery, validateEntityState, withEntityWriterLock } from "./entityStorage.js";
+import { EntityPublicationContext } from "./entityPublicationContext.js";
 import { inspectPendingPlanReplacement, publishPlanReplacement, recoverPendingPlanReplacement } from "./planReplacementTransaction.js";
-import { detectStateModeBinding } from "./stateMode.js";
+import { detectStateModeBinding, freshEntityStateMarker, freshPlanInitialization } from "./stateMode.js";
 import { normalizeAndValidatePlanCreateInput, validatePlanPublicationCandidate } from "./write/planPublication.js";
 import { reject } from "./write/errors.js";
 import { mutatePlanTaskEvaluation, planTaskRecordViolations } from "./write/planEvaluation.js";
@@ -249,8 +250,24 @@ export function createPlanEntities(req, options = {}) {
     }
     return withEntityWriterLock(options.publicationContext, () => createPlanEntitiesUnderLock(req, options));
 }
+/** The first Plan is the sole marker-absent entity initializer. */
+export function createFreshPlanEntities(req, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const initialization = freshPlanInitialization(req.projectRoot, sourceRoot);
+    if (!initialization)
+        return null;
+    const publicationContext = EntityPublicationContext.beginInitialization(initialization.root, initialization.markerPath);
+    try {
+        return createPlanEntities(req, { ...options, sourceRoot, publicationContext });
+    }
+    finally {
+        publicationContext.close();
+    }
+}
 function createPlanEntitiesUnderLock(req, options) {
     const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const initializing = options.publicationContext.isInitializing();
+    const marker = initializing ? freshEntityStateMarker(sourceRoot) : null;
     const input = preparedPlanCreateInput(req);
     const discovery = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
     const entities = all(options.publicationContext.pinnedPath(), sourceRoot, discovery);
@@ -292,8 +309,21 @@ function createPlanEntitiesUnderLock(req, options) {
         return record;
     });
     const publications = [{ boundary: PLAN, id: planId, record: planRecord }, ...taskRecords.map((record, index) => ({ boundary: TASK, id: taskIds[index], record }))];
+    const resultExtra = {
+        tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })),
+        effects: lifecycle.effects,
+        ...(marker ? {
+            initialization: {
+                atomic: true,
+                marker: {
+                    path: path.join(req.projectRoot, options.publicationContext.markerPath),
+                    record: marker,
+                },
+            },
+        } : {}),
+    };
     if (req.dryRun)
-        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, true, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, true, resultExtra);
     if (command === "state plan replace" && lifecycle.predecessor && lifecycle.archivedRecord && lifecycle.replacementInputSha256) {
         const targets = [
             {
@@ -314,10 +344,11 @@ function createPlanEntitiesUnderLock(req, options) {
                     throw new Error(`targeted plan replacement graph failed state validation: ${validation.issues.map(({ message }) => message).join("; ")}`);
             },
         });
-        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, resultExtra);
     }
     const published = [];
     let predecessor;
+    let markerIdentity;
     try {
         if (lifecycle.predecessor && lifecycle.archivedRecord) {
             const archived = replaceEntityUnderLock({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: PLAN, id: lifecycle.predecessor.id, expectedRecord: lifecycle.predecessor.record, expectedBytes: exactDiscoveredEntityBytes(lifecycle.predecessor), migrationProvenance: lifecycle.predecessor.migrationProvenance, record: lifecycle.archivedRecord });
@@ -338,6 +369,10 @@ function createPlanEntitiesUnderLock(req, options) {
         if (!validation.valid)
             throw new Error(`created plan graph failed state validation: ${validation.issues.map(({ message }) => message).join("; ")}`);
         options.publicationContext.assertValid();
+        if (marker) {
+            markerIdentity = options.publicationContext.publishStateMarker(dumpYamlMapping(marker));
+            options.publicationContext.assertValid();
+        }
     }
     catch (error) {
         const recoveryFailures = [];
@@ -359,11 +394,21 @@ function createPlanEntitiesUnderLock(req, options) {
                 recoveryFailures.push(`predecessor restoration failed because ownership changed or publication was unsafe: ${restoreError.message}`);
             }
         }
+        if (markerIdentity) {
+            try {
+                const removed = options.publicationContext.removeExact(options.publicationContext.markerPath, markerIdentity, false);
+                if (removed === "identity_mismatch")
+                    recoveryFailures.push("cleanup ownership changed for fresh state marker");
+            }
+            catch (cleanupError) {
+                recoveryFailures.push(`cleanup failed for fresh state marker: ${cleanupError.message}`);
+            }
+        }
         if (recoveryFailures.length)
             throw new Error(`plan replacement failed: ${error.message}; recovery failed: ${recoveryFailures.join("; ")}`, { cause: error });
         throw error;
     }
-    return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+    return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, resultExtra);
 }
 function replacementEffects(predecessor, successor) {
     return {

package/dist/state/progressWritePolicy.js

@@ -0,0 +1,33 @@
+const APPEND_GUIDANCE = "Append progress only for durable project truth that future work needs, a required glossary_caveat lifecycle event, or a plan-completion sweep. Glossary caveats and plan-completion sweeps require a record; an ordinary build or release attempt with no durable project truth change, and an outcome future work does not need as a milestone, require no progress append.";
+const RECEIPT_GUIDANCE = "Qualification and publication receipts own timings, integrity, digests, retries, and replay; do not duplicate receipt detail in progress.";
+const PROGRESS_WRITE_POLICY = {
+    schemaVersion: "agentera.progressWritePolicy.v1",
+    append: {
+        mode: "conditional",
+        allowed_when: [
+            "durable_project_truth_needed_by_future_work",
+            "required_glossary_caveat",
+            "plan_completion_sweep",
+        ],
+        required_when: [
+            "required_glossary_caveat",
+            "plan_completion_sweep",
+        ],
+        no_append_required_when: [
+            "ordinary_build_or_release_attempt_without_durable_project_truth_change",
+            "durable_outcome_not_needed_by_future_work",
+        ],
+        guidance: APPEND_GUIDANCE,
+    },
+    receipt_detail: {
+        owners: ["qualification_receipt", "publication_receipt"],
+        fields: ["timings", "integrity", "digests", "retries", "replay"],
+        guidance: RECEIPT_GUIDANCE,
+    },
+};
+export function progressWritePolicy() {
+    return structuredClone(PROGRESS_WRITE_POLICY);
+}
+export function progressWriteGuidance() {
+    return [APPEND_GUIDANCE, RECEIPT_GUIDANCE];
+}