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

package/dist/state/stateMode.js

@@ -1,7 +1,8 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { loadYamlMapping } from "../core/yaml.js";
+import { dumpYamlMapping, loadYamlMapping } from "../core/yaml.js";
 import { EntityPublicationContext } from "./entityPublicationContext.js";
 import { validateRealProjectRoot } from "./projectRoot.js";
 import { readProjectFileSnapshot } from "./safeProjectFile.js";
@@ -44,6 +45,142 @@ function readStableMarker(root, markerPath) {
     }
     return snapshot.bytes;
 }
+function pathKind(root, relativePath) {
+    const absolute = path.join(root.path, ...relativePath.split("/"));
+    try {
+        const stat = fs.lstatSync(absolute);
+        if (stat.isSymbolicLink())
+            return "unsafe";
+        if (stat.isFile())
+            return "file";
+        if (stat.isDirectory())
+            return "directory";
+        return "unsafe";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        return "unsafe";
+    }
+}
+function isGitWorktreeRoot(root) {
+    const env = { ...process.env };
+    for (const name of ["GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR"])
+        delete env[name];
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: root.path,
+        env,
+        encoding: "utf8",
+    });
+    if (result.error || result.status !== 0)
+        return false;
+    try {
+        return fs.realpathSync(String(result.stdout).trim()) === root.path;
+    }
+    catch {
+        return false;
+    }
+}
+function classifyMarkerAbsentProject(root, markerPath) {
+    const stateRoot = pathKind(root, ".agentera");
+    if (stateRoot === "missing") {
+        return {
+            state: isGitWorktreeRoot(root) ? "fresh_uninitialized" : "unknown",
+            root,
+            markerPath,
+        };
+    }
+    if (stateRoot !== "directory") {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "Agentera state root '.agentera' is not a safe directory",
+        };
+    }
+    const entities = pathKind(root, ".agentera/entities");
+    if (entities !== "missing" && entities !== "directory") {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "Agentera entity root '.agentera/entities' is not a safe directory",
+        };
+    }
+    if (entities === "directory")
+        return { state: "partial", root, markerPath };
+    const aggregates = ["plan.yaml", "progress.yaml", "decisions.yaml", "health.yaml"]
+        .map((name) => pathKind(root, `.agentera/${name}`));
+    if (aggregates.includes("unsafe")) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "a recognized Agentera aggregate is not a safe regular file",
+        };
+    }
+    const aggregateCount = aggregates.filter((kind) => kind === "file").length;
+    if (aggregateCount >= 2)
+        return { state: "legacy", root, markerPath };
+    if (aggregateCount === 1)
+        return { state: "partial", root, markerPath };
+    return { state: "unknown", root, markerPath };
+}
+/** Classify local state without creating, repairing, or adopting project files. */
+export function classifyProjectState(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const root = validateRealProjectRoot(projectRoot);
+    const declared = contract(sourceRoot);
+    let bytes;
+    try {
+        bytes = readStableMarker(root, declared.markerPath);
+    }
+    catch (error) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath: declared.markerPath,
+            reason: error.message,
+        };
+    }
+    if (bytes === null)
+        return classifyMarkerAbsentProject(root, declared.markerPath);
+    try {
+        const document = loadYamlMapping(bytes.toString("utf8"));
+        if (document.schemaVersion !== declared.schemaVersion || document.mode !== declared.mode) {
+            return {
+                state: "corrupt",
+                root,
+                markerPath: declared.markerPath,
+                reason: `state mode marker '${declared.markerPath}' must declare schemaVersion '${declared.schemaVersion}' and mode '${declared.mode}'; restore the durable migration marker before retrying`,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath: declared.markerPath,
+            reason: `state mode marker '${declared.markerPath}' is corrupt: ${error.message}; restore the durable migration marker before retrying`,
+        };
+    }
+    return { state: "entities", root, markerPath: declared.markerPath, markerBytes: bytes };
+}
+export function freshEntityStateMarker(sourceRoot = resolveSourceRoot()) {
+    const declared = contract(sourceRoot);
+    return { schemaVersion: declared.schemaVersion, mode: declared.mode };
+}
+export function freshPlanInitialization(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const classified = classifyProjectState(projectRoot, sourceRoot);
+    if (classified.state !== "fresh_uninitialized")
+        return null;
+    const marker = freshEntityStateMarker(sourceRoot);
+    return {
+        root: classified.root,
+        markerPath: classified.markerPath,
+        marker,
+        markerBytes: dumpYamlMapping(marker),
+    };
+}
 function detectValidatedStateMode(projectRoot, sourceRoot) {
     const root = validateRealProjectRoot(projectRoot);
     const declared = contract(sourceRoot);

package/dist/state/todoDocsEntities.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { StateRetrievalFailure } from "./directRetrieval.js";
-import { allocateEntityId, assertEntityDiscoveryOrigin, canonicalEntityEnvelopeBytes, canonicalEntityRecordViolations, discoverEntities, entityExactGetMaxBytes, exactDiscoveredEntityBytes, publishEntityUnderLock, replaceEntityUnderLock, validateEntityState, withEntityWriterLock, } from "./entityStorage.js";
+import { allocateEntityId, assertEntityDiscoveryOrigin, canonicalEntityEnvelopeBytes, canonicalEntityRecordViolations, discoverEntities, entityExactGetMaxBytes, exactDiscoveredEntityBytes, publishEntityUnderLock, replaceEntityUnderLock, validateEntityState, withEntityWriterLock } from "./entityStorage.js";
 import { detectStateModeBinding } from "./stateMode.js";
 import { reject, StateWriteInputError } from "./write/errors.js";
 import { TODO_SEVERITIES, TODO_STATUSES, todoDocsRecordViolations, todoInputViolations } from "./todoDocsEntityValidation.js";
@@ -18,8 +18,8 @@ import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMa
 import { evaluateTodoReadinessQueue } from "../cli/todoReadinessSelection.js";
 import { artifactSchemasDir, loadArtifactRecord, registryModelPath, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { inspectTodoReconciliation, publishTodoReconciliation, recoverTodoReconciliation, todoCreateRequestSha256 } from "./todoReconciliationTransaction.js";
-import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_ACTIVATION_RISK_LIMIT, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, todoActivationEffect, todoRepairEffect, unchangedTodoActivationEffect, } from "./todoReconciliationActivation.js";
-import { planTodoRepair } from "./todoReconciliationRepair.js";
+import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_ACTIVATION_RISK_LIMIT, TODO_OWNER_CORRECTION_APPLY_COMMAND, TODO_OWNER_CORRECTION_PREVIEW_COMMAND, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, todoActivationEffect, todoOwnerCorrectionEffect, todoRepairEffect, unchangedTodoActivationEffect } from "./todoReconciliationActivation.js";
+import { normalizeTodoOwnerCorrectionEvidence, planTodoOwnerCorrection, planTodoRepair } from "./todoReconciliationRepair.js";
 import { readTodoMarkdown, renderManagedMarkdown } from "./todoMarkdownProjection.js";
 import { inactiveTodoActivationSafety, rejectUnsafeInactiveTodoActivation, unsafeInactiveDuplicateDiagnosis } from "./todoActivationSafety.js";
 const ID = /^[a-z]{10}$/;
@@ -412,6 +412,7 @@ function withBaseline(record, value) { const publicValue = Object.fromEntries(Ob
 function inactiveTodoMutation() { reject({ class: "conflict", message: "TODO reconciliation is inactive; ordinary TODO mutations cannot activate it implicitly", syntax: TODO_ACTIVATION_PREVIEW_COMMAND, example: TODO_ACTIVATION_APPLY_COMMAND, recovery: `Run exactly '${TODO_ACTIVATION_PREVIEW_COMMAND}', review every reported effect, then run exactly '${TODO_ACTIVATION_APPLY_COMMAND}'; no state was changed.` }); }
 function activationEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo activate", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "activate", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, activation: effect, apply_command: TODO_ACTIVATION_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
 function repairEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo repair", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "repair", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, repair: effect, apply_command: TODO_REPAIR_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
+function ownerCorrectionEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo correct-owners", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "correct-owners", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, correction: effect, apply_command: TODO_OWNER_CORRECTION_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
 function envelope(command, entity, artifact, record, dryRun) { return { schemaVersion: "agentera.stateWrite.v1", command, status: "pass", path: entity.path, id: entity.id, artifact, record, operation: { verb: command.split(" ").at(-1), dry_run: dryRun, idempotent_replay: entity.replay }, validation: { status: "pass", violations: [] } }; }
 function targetPath(root, sourceRoot, artifact, id) {
     const model = definition(artifact);
@@ -665,12 +666,14 @@ export function mutateTodoDocsEntity(req, options = {}) {
         const sourceBinding = { kind: "project", projectRoot: context.validatedRoot };
         context.assertValid();
         const todoBinding = artifact === "todo" ? todoReconciliationBinding(req.projectRoot, sourceRoot) : null;
+        const correctingOwners = artifact === "todo" && req.spec.verb === "correct-owners";
+        const ownerEvidence = correctingOwners ? normalizeTodoOwnerCorrectionEvidence(req.input ?? {}) : null;
         const pending = todoBinding ? inspectTodoReconciliation(pinnedRoot, todoBinding) : [];
         const initialActivation = artifact === "todo" ? loadTodoReconciliationActivation(pinnedRoot) : null;
-        if (artifact === "todo" && ["activate", "repair"].includes(req.spec.verb)) {
+        if (artifact === "todo" && ["activate", "repair", "correct-owners"].includes(req.spec.verb)) {
             const repairing = req.spec.verb === "repair";
-            const previewCommand = repairing ? TODO_REPAIR_PREVIEW_COMMAND : TODO_ACTIVATION_PREVIEW_COMMAND;
-            const applyCommand = repairing ? TODO_REPAIR_APPLY_COMMAND : TODO_ACTIVATION_APPLY_COMMAND;
+            const previewCommand = correctingOwners ? TODO_OWNER_CORRECTION_PREVIEW_COMMAND : repairing ? TODO_REPAIR_PREVIEW_COMMAND : TODO_ACTIVATION_PREVIEW_COMMAND;
+            const applyCommand = correctingOwners ? TODO_OWNER_CORRECTION_APPLY_COMMAND : repairing ? TODO_REPAIR_APPLY_COMMAND : TODO_ACTIVATION_APPLY_COMMAND;
             if (repairing && !initialActivation)
                 reject({ class: "conflict", message: "TODO repair requires an existing reconciliation activation marker", recovery: `Use '${TODO_ACTIVATION_PREVIEW_COMMAND}' for an inactive project; no state was changed.` });
             if (req.dryRun && (req.values.confirmed === true || req.values.effect_sha256 !== undefined))
@@ -687,7 +690,8 @@ export function mutateTodoDocsEntity(req, options = {}) {
         const recoveryReceipts = todoBinding && !req.dryRun
             ? recoverTodoReconciliation(context, sourceRoot, todoBinding, {
                 createRequestSha256,
-                ...(["activate", "repair"].includes(req.spec.verb) ? { activationEffectSha256: String(req.values.effect_sha256) } : {}),
+                ...(["activate", "repair", "correct-owners"].includes(req.spec.verb) ? { activationEffectSha256: String(req.values.effect_sha256) } : {}),
+                ...(correctingOwners ? { ownerMappingSha256: ownerEvidence.sha256 } : {}),
                 beforeCommit: () => assertState(pinnedRoot, sourceRoot, sourceBinding),
             })
             : [];
@@ -767,6 +771,57 @@ export function mutateTodoDocsEntity(req, options = {}) {
                 context.assertValid();
                 return activationEnvelope(effect, false, false, transaction.id, transaction.targetCount, recovered);
             }
+            if (req.spec.verb === "correct-owners") {
+                if (activation) {
+                    if (!req.dryRun && activation.effect_operation === "correct-owners" && activation.effect_sha256 === req.values.effect_sha256 && activation.owner_mapping_sha256 === ownerEvidence.sha256) {
+                        const replayEffect = todoOwnerCorrectionEffect({ counts: { matched: 0, converted: 0, retained: 0, duplicate: 0, stale: 0, conflicting: 0 }, items: [], omitted_count: 0 }, ownerEvidence.sha256, [], publicRelative, markdownBefore, markdown);
+                        replayEffect.effect_sha256 = activation.effect_sha256;
+                        return ownerCorrectionEnvelope(replayEffect, false, true, null, 0, recovered);
+                    }
+                    reject({ class: "conflict", message: "TODO owner correction requires marker-absent unsafe-inactive state", recovery: "Use state todo repair only for an unsafe active reconciliation, or retry the exact owner-correction apply command when its stored effect and owner mapping match; no state was changed." });
+                }
+                let unsafe = true;
+                try {
+                    unsafe = !inactiveTodoActivationSafety(managedRows(markdown, null, todoEntities), todoEntities).safe;
+                }
+                catch {
+                    unsafe = true;
+                }
+                if (!unsafe)
+                    reject({ class: "conflict", message: "TODO owner correction requires marker-absent unsafe-inactive state", recovery: `Use '${TODO_ACTIVATION_PREVIEW_COMMAND}' for a safe inactive project; no state was changed.` });
+                const plan = planTodoOwnerCorrection(markdown, todoEntities, ownerEvidence);
+                for (const [todoId, record] of plan.records) {
+                    const violations = recordViolations("todo", record, sourceRoot);
+                    if (violations.length)
+                        reject({ class: "schema_violation", message: "todo entity input is invalid", violations });
+                    if (record.readiness !== undefined)
+                        assertTodoReferences(todoId, record, [...plan.records].map(([entityId, entityRecord]) => ({ boundary: TODO.boundary, id: entityId, record: entityRecord })));
+                }
+                let activationBytesAfter = todoReconciliationActivationBytes([], "0".repeat(64), "correct-owners", ownerEvidence.sha256);
+                const activationAfter = JSON.parse(activationBytesAfter);
+                const finalRows = managedRows(plan.rendered, activationAfter, todoEntities).rows;
+                for (const [todoId, record] of plan.records) {
+                    const row = finalRows.get(todoId);
+                    plan.records.set(todoId, withBaseline(record, row ? rowSnapshot(row, record) : { present: false }));
+                }
+                const targets = todoEntities.map((entity) => ({ path: entity.relativePath, before: exactDiscoveredEntityBytes(entity), after: canonicalEntityEnvelopeBytes({ id: entity.id, artifact: "todo", record: plan.records.get(entity.id), migrationProvenance: entity.migrationProvenance ?? undefined }) }));
+                targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: activationBytesAfter });
+                targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: plan.rendered });
+                const preliminaryEffect = todoOwnerCorrectionEffect(plan.diagnosis, ownerEvidence.sha256, targets, publicRelative, markdownBefore, plan.rendered);
+                activationBytesAfter = todoReconciliationActivationBytes([], String(preliminaryEffect.effect_sha256), "correct-owners", ownerEvidence.sha256);
+                targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH).after = activationBytesAfter;
+                const effect = todoOwnerCorrectionEffect(plan.diagnosis, ownerEvidence.sha256, targets, publicRelative, markdownBefore, plan.rendered);
+                if (effect.effect_sha256 !== preliminaryEffect.effect_sha256)
+                    throw new Error("TODO owner correction effect authorization is not self-consistent");
+                if (req.dryRun)
+                    return ownerCorrectionEnvelope(effect, true, false, null, effect.targets.length, recovered);
+                if (req.values.effect_sha256 !== effect.effect_sha256)
+                    reject({ class: "conflict", message: "TODO owner correction effects changed after preview", syntax: TODO_OWNER_CORRECTION_PREVIEW_COMMAND, example: TODO_OWNER_CORRECTION_APPLY_COMMAND, recovery: `Rerun exactly '${TODO_OWNER_CORRECTION_PREVIEW_COMMAND}', review the changed bounded effects, then run its new exact apply_command; no state was changed.` });
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, { activationEffectSha256: String(effect.effect_sha256), ownerMappingSha256: ownerEvidence.sha256, interruptAfterTarget: options.interruptAfterTarget, beforeCommit: () => { assertState(pinnedRoot, sourceRoot, sourceBinding); const currentBinding = todoReconciliationBinding(req.projectRoot, sourceRoot); if (currentBinding.publicPath !== todoBinding.publicPath || currentBinding.mappingSha256 !== todoBinding.mappingSha256)
+                        reject({ class: "conflict", message: "TODO reconciliation mapping changed during owner correction publication", recovery: "Preserve the changed docs mapping and retry owner correction after every transaction target is restored; no mapping bytes were overwritten." }); } });
+                context.assertValid();
+                return ownerCorrectionEnvelope(effect, false, false, transaction.id, transaction.targetCount, recovered);
+            }
             if (req.spec.verb === "repair") {
                 if (!activation || !loadedActivation)
                     throw new Error("TODO repair lost its required activation marker");

package/dist/state/todoReconciliationActivation.js

@@ -13,7 +13,10 @@ export const TODO_ACTIVATION_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} sta
 export const TODO_ACTIVATION_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json`;
 export const TODO_REPAIR_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --dry-run --format json`;
 export const TODO_REPAIR_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json`;
-export const TODO_UNSAFE_INACTIVE_RECOVERY = "Owner correction required: restore Markdown-owned public rows and Agentera-owned entity status to exact one-to-one pre-activation evidence. Do not activate or repair. If a correction needs a mutation, stop and request replanning; no state was changed.";
+export const TODO_OWNER_CORRECTION_INPUT_VERSION = "agentera.todoOwnerCorrection.v1";
+export const TODO_OWNER_CORRECTION_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo correct-owners --input OWNER_MAPPING.yaml --dry-run --format json`;
+export const TODO_OWNER_CORRECTION_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo correct-owners --input OWNER_MAPPING.yaml --effect-sha256 EFFECT_SHA256 --yes --format json`;
+export const TODO_UNSAFE_INACTIVE_RECOVERY = `Owner correction required: run exactly '${TODO_OWNER_CORRECTION_PREVIEW_COMMAND}', then use its exact apply_command; no state was changed.`;
 export const TODO_ACTIVATION_RISK_LIMIT = 20;
 function activationFailure(message) {
     reject({
@@ -25,7 +28,7 @@ function activationFailure(message) {
 export function todoLegacyRowFingerprint(section, line) {
     return createHash("sha256").update(section).update("\0").update(line).digest("hex");
 }
-export function todoReconciliationActivationBytes(retainedLegacyRows, effectSha256, effectOperation = "activate") {
+export function todoReconciliationActivationBytes(retainedLegacyRows, effectSha256, effectOperation = "activate", ownerMappingSha256) {
     const retained = [...retainedLegacyRows].sort();
     if (retained.length > TODO_RECONCILIATION_ITEM_LIMIT
         || new Set(retained).size !== retained.length
@@ -33,11 +36,18 @@ export function todoReconciliationActivationBytes(retainedLegacyRows, effectSha2
         activationFailure("TODO reconciliation activation has invalid retained legacy-row identities");
     if (effectSha256 !== undefined && !SHA256.test(effectSha256))
         activationFailure("TODO reconciliation activation has an invalid effect authorization");
+    if (ownerMappingSha256 !== undefined && !SHA256.test(ownerMappingSha256))
+        activationFailure("TODO reconciliation activation has an invalid owner-mapping authorization");
+    if (effectOperation === "correct-owners" && (effectSha256 === undefined || ownerMappingSha256 === undefined))
+        activationFailure("TODO owner correction activation requires effect and owner-mapping authorization");
+    if (effectOperation !== "correct-owners" && ownerMappingSha256 !== undefined)
+        activationFailure("TODO reconciliation activation owner-mapping authorization requires owner correction");
     return `${JSON.stringify({
         schema_version: TODO_RECONCILIATION_ACTIVATION_VERSION,
         retained_legacy_rows: retained,
         ...(effectSha256 ? { effect_sha256: effectSha256 } : {}),
         ...(effectSha256 ? { effect_operation: effectOperation } : {}),
+        ...(ownerMappingSha256 ? { owner_mapping_sha256: ownerMappingSha256 } : {}),
     })}\n`;
 }
 export function loadTodoReconciliationActivation(root) {
@@ -63,14 +73,17 @@ export function loadTodoReconciliationActivation(root) {
         activationFailure("TODO reconciliation activation is not a mapping");
     }
     const record = value;
-    if (!["retained_legacy_rows,schema_version", "effect_operation,effect_sha256,retained_legacy_rows,schema_version", "effect_sha256,retained_legacy_rows,schema_version"].includes(Object.keys(record).sort().join(","))
+    if (!["retained_legacy_rows,schema_version", "effect_operation,effect_sha256,retained_legacy_rows,schema_version", "effect_operation,effect_sha256,owner_mapping_sha256,retained_legacy_rows,schema_version", "effect_sha256,retained_legacy_rows,schema_version"].includes(Object.keys(record).sort().join(","))
         || record.schema_version !== TODO_RECONCILIATION_ACTIVATION_VERSION
         || !Array.isArray(record.retained_legacy_rows)
         || record.retained_legacy_rows.length > TODO_RECONCILIATION_ITEM_LIMIT
         || record.retained_legacy_rows.some((digest) => typeof digest !== "string" || !SHA256.test(digest))
         || new Set(record.retained_legacy_rows).size !== record.retained_legacy_rows.length
         || (record.effect_sha256 !== undefined && (typeof record.effect_sha256 !== "string" || !SHA256.test(record.effect_sha256)))
-        || (record.effect_operation !== undefined && !["activate", "repair"].includes(record.effect_operation)))
+        || (record.effect_operation !== undefined && !["activate", "repair", "correct-owners"].includes(record.effect_operation))
+        || (record.owner_mapping_sha256 !== undefined && (typeof record.owner_mapping_sha256 !== "string" || !SHA256.test(record.owner_mapping_sha256)))
+        || (record.effect_operation === "correct-owners" && (record.effect_sha256 === undefined || record.owner_mapping_sha256 === undefined))
+        || (record.effect_operation !== "correct-owners" && record.owner_mapping_sha256 !== undefined))
         activationFailure("TODO reconciliation activation has an invalid canonical record");
     return { record: record, bytes };
 }
@@ -138,3 +151,32 @@ export function todoRepairEffect(diagnosis, targets, publicPath, markdownBefore,
     const authorizedTargets = changedTargets.map((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH ? { ...target, after_sha256: normalizedActivationSha256 } : target);
     return { ...evidence, effect_sha256: sha256(canonicalRecordJson({ ...evidence, targets: authorizedTargets })) };
 }
+export function todoOwnerCorrectionEffect(diagnosis, ownerMappingSha256, targets, publicPath, markdownBefore, rendered) {
+    const changedTargets = targets
+        .filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after)))
+        .map((target) => ({ path: target.path, before_sha256: target.before === null ? null : sha256(target.before), after_sha256: sha256(target.after) }));
+    const evidence = {
+        diagnosis,
+        owner_mapping_sha256: ownerMappingSha256,
+        targets: changedTargets,
+        public_document: {
+            path: publicPath,
+            changed: !markdownBefore.equals(Buffer.from(rendered)),
+            before_bytes: markdownBefore.length,
+            after_bytes: Buffer.byteLength(rendered),
+            before_sha256: sha256(markdownBefore),
+            after_sha256: sha256(rendered),
+            changed_lines: boundedPublicChanges(markdownBefore.toString("utf8"), rendered),
+        },
+    };
+    const activationTarget = targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH);
+    let normalizedActivationSha256 = null;
+    if (activationTarget) {
+        const parsed = JSON.parse(activationTarget.after);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || typeof parsed.effect_sha256 !== "string")
+            throw new Error("TODO owner correction activation target cannot be normalized for effect authorization");
+        normalizedActivationSha256 = sha256(canonicalRecordJson({ ...parsed, effect_sha256: "activation_effect_authorization" }));
+    }
+    const authorizedTargets = changedTargets.map((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH ? { ...target, after_sha256: normalizedActivationSha256 } : target);
+    return { ...evidence, effect_sha256: sha256(canonicalRecordJson({ ...evidence, targets: authorizedTargets })) };
+}

package/dist/state/todoReconciliationInspection.js

@@ -5,7 +5,7 @@ import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { detectStateMode } from "./stateMode.js";
 import { StateWriteInputError } from "./write/errors.js";
-import { TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, TODO_UNSAFE_INACTIVE_RECOVERY, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
+import { TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_OWNER_CORRECTION_APPLY_COMMAND, TODO_OWNER_CORRECTION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, TODO_UNSAFE_INACTIVE_RECOVERY, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
 import { planTodoRepair } from "./todoReconciliationRepair.js";
 import { readTodoMarkdown } from "./todoMarkdownProjection.js";
 import { inactiveTodoActivationSafety } from "./todoActivationSafety.js";
@@ -47,8 +47,8 @@ function invalidLifecycle() {
 function inspection(state, rawCounts, risks) {
     const bounded = boundedCounts(rawCounts);
     const active = state === "healthy_active" || state === "unsafe_active";
-    const preview = state === "inactive" ? TODO_ACTIVATION_PREVIEW_COMMAND : active ? TODO_REPAIR_PREVIEW_COMMAND : null;
-    const apply = state === "inactive" ? TODO_ACTIVATION_APPLY_COMMAND : active ? TODO_REPAIR_APPLY_COMMAND : null;
+    const preview = state === "unsafe_inactive" ? TODO_OWNER_CORRECTION_PREVIEW_COMMAND : state === "inactive" ? TODO_ACTIVATION_PREVIEW_COMMAND : active ? TODO_REPAIR_PREVIEW_COMMAND : null;
+    const apply = state === "unsafe_inactive" ? TODO_OWNER_CORRECTION_APPLY_COMMAND : state === "inactive" ? TODO_ACTIVATION_APPLY_COMMAND : active ? TODO_REPAIR_APPLY_COMMAND : null;
     return {
         state,
         status: state === "healthy_active" ? "operable" : "action_required",
@@ -106,6 +106,8 @@ export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceR
     if (!activation) {
         try {
             const scan = managedRows(readTodoMarkdown(todoPublicPath(root, sourceRoot)).text, null, entities);
+            if (entities.length === 0 && scan.matchedRows === 0 && scan.retainedLegacyRows.length === 0)
+                return null;
             const safety = inactiveTodoActivationSafety(scan, entities);
             return inspection(safety.safe ? "inactive" : "unsafe_inactive", safety.counts, safety.safe ? undefined : safety.risks);
         }

package/dist/state/todoReconciliationRepair.js

@@ -1,6 +1,8 @@
+import { createHash } from "node:crypto";
 import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { reject } from "./write/errors.js";
-import { todoLegacyRowFingerprint, TODO_REPAIR_PREVIEW_COMMAND } from "./todoReconciliationActivation.js";
+import { todoLegacyRowFingerprint, TODO_OWNER_CORRECTION_INPUT_VERSION, TODO_OWNER_CORRECTION_PREVIEW_COMMAND, TODO_REPAIR_PREVIEW_COMMAND } from "./todoReconciliationActivation.js";
 const RECONCILIATION_VERSION = "agentera.todoReconciliation.v1";
 const DIAGNOSTIC_LIMIT = 20;
 function mapping(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
@@ -30,6 +32,64 @@ function importMarkdown(record, row) {
     return result;
 }
 function rowFor(id, record) { return `- [${record.status === "resolved" ? "x" : " "}] [id:${id}] ${renderTodoPublicRecord(record)}`; }
+export function todoOwnerCorrectionInputViolations(input) {
+    const violations = [];
+    const allowed = new Set(["schema_version", "owners"]);
+    for (const key of Object.keys(input))
+        if (!allowed.has(key))
+            violations.push(`input field '${key}' is not accepted for owner correction`);
+    if (input.schema_version !== TODO_OWNER_CORRECTION_INPUT_VERSION)
+        violations.push(`schema_version must be '${TODO_OWNER_CORRECTION_INPUT_VERSION}'`);
+    if (!Array.isArray(input.owners)) {
+        violations.push("owners must be a list of owner mappings");
+        return violations;
+    }
+    if (input.owners.length === 0 || input.owners.length > 256)
+        violations.push("owners must contain 1..256 mappings");
+    const ids = new Set();
+    const lines = new Set();
+    input.owners.forEach((owner, index) => {
+        if (!mapping(owner)) {
+            violations.push(`owners[${index}] must be a mapping`);
+            return;
+        }
+        const keys = Object.keys(owner).sort().join(",");
+        if (keys !== "id,source_line")
+            violations.push(`owners[${index}] must contain only id and source_line`);
+        if (typeof owner.id !== "string" || !/^[a-z]{10}$/.test(owner.id))
+            violations.push(`owners[${index}].id must be a bare ten-letter TODO ID`);
+        else if (ids.has(owner.id))
+            violations.push(`owners[${index}].id duplicates another owner claim`);
+        else
+            ids.add(owner.id);
+        if (!Number.isSafeInteger(owner.source_line) || Number(owner.source_line) < 1)
+            violations.push(`owners[${index}].source_line must be a positive integer`);
+        else if (lines.has(Number(owner.source_line)))
+            violations.push(`owners[${index}].source_line duplicates another owner claim`);
+        else
+            lines.add(Number(owner.source_line));
+    });
+    return violations.length <= DIAGNOSTIC_LIMIT
+        ? violations
+        : [...violations.slice(0, DIAGNOSTIC_LIMIT), `${violations.length - DIAGNOSTIC_LIMIT} additional input violations omitted`];
+}
+export function normalizeTodoOwnerCorrectionEvidence(input) {
+    const violations = todoOwnerCorrectionInputViolations(input);
+    if (violations.length)
+        reject({
+            class: "schema_violation",
+            message: "TODO owner correction input is invalid",
+            violations,
+            recovery: `Run exactly '${TODO_OWNER_CORRECTION_PREVIEW_COMMAND}' with one complete schema-valid owner mapping; no state was changed.`,
+        });
+    const owners = input.owners
+        .map((owner) => ({ id: String(owner.id), source_line: Number(owner.source_line) }))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    return {
+        owners,
+        sha256: createHash("sha256").update(canonicalRecordJson({ schema_version: TODO_OWNER_CORRECTION_INPUT_VERSION, owners })).digest("hex"),
+    };
+}
 function scanRows(markdown) {
     const managed = new Map();
     const legacy = [];
@@ -168,3 +228,91 @@ export function planTodoRepair(markdown, activation, entities) {
     const retainedLegacyRows = retainedRows.filter((row) => !claimedLegacy.has(row.line)).map((row) => todoLegacyRowFingerprint(row.section, row.sourceLine)).sort();
     return { records, retainedLegacyRows, rendered, diagnosis: { counts: { duplicate, stale, matched, retained: retainedLegacyRows.length, conflicting: 0 }, items, omitted_count: Math.max(0, duplicate + matched + retainedLegacyRows.length - items.length) } };
 }
+function correctedRow(row, id, record) {
+    const indent = row.sourceLine.match(/^\s*/)?.[0] ?? "";
+    return `${indent}${rowFor(id, record)}`;
+}
+export function planTodoOwnerCorrection(markdown, entities, evidence) {
+    const { managed, legacy } = scanRows(markdown);
+    const rows = new Map();
+    for (const row of legacy)
+        rows.set(row.line, row);
+    for (const entries of managed.values())
+        for (const row of entries)
+            rows.set(row.line, row);
+    const byId = new Map(entities.filter((entity) => Boolean(entity.id && entity.record)).map((entity) => [entity.id, entity]));
+    const conflicts = [];
+    const claimedIds = new Set();
+    const claimedLines = new Set();
+    const records = new Map();
+    const replacements = new Map();
+    const items = [];
+    let stale = 0;
+    for (const owner of evidence.owners) {
+        const entity = byId.get(owner.id);
+        const row = rows.get(owner.source_line - 1);
+        if (!entity) {
+            conflicts.push(`owner ID '${owner.id}' has no canonical entity`);
+            continue;
+        }
+        if (!row) {
+            conflicts.push(`owner source line ${owner.source_line} has no managed TODO row`);
+            continue;
+        }
+        if (row.item.id && row.item.id !== owner.id) {
+            conflicts.push(`owner source line ${owner.source_line} already names '${row.item.id}', not '${owner.id}'`);
+            continue;
+        }
+        if (!claimedIds.add(owner.id) || !claimedLines.add(row.line)) {
+            conflicts.push(`owner mapping duplicates ID '${owner.id}' or source line ${owner.source_line}`);
+            continue;
+        }
+        if (entity.record.status === "resolved" && row.item.status === "open") {
+            conflicts.push(`owner source line ${owner.source_line} would reopen completed TODO '${owner.id}'`);
+            continue;
+        }
+        const record = importMarkdown(entity.record, row);
+        const stalePublic = !samePublic(publicSnapshot(entity.record), rowSnapshot(row, entity.record));
+        if (stalePublic)
+            stale += 1;
+        records.set(owner.id, record);
+        replacements.set(row.line, correctedRow(row, owner.id, record));
+        if (items.length < DIAGNOSTIC_LIMIT)
+            items.push({ id: owner.id, source_line: owner.source_line, stale_public: stalePublic });
+    }
+    for (const id of byId.keys())
+        if (!claimedIds.has(id))
+            conflicts.push(`canonical TODO entity '${id}' has no owner mapping`);
+    for (const [line, row] of rows)
+        if (!claimedLines.has(line))
+            conflicts.push(`managed TODO row at line ${row.line + 1} has no owner mapping`);
+    for (const [id, entries] of managed) {
+        if (entries.length > 1)
+            conflicts.push(`managed ID '${id}' occurs at lines ${entries.map((row) => row.line + 1).join(", ")}`);
+        if (!byId.has(id))
+            conflicts.push(`managed ID '${id}' has no canonical entity`);
+    }
+    if (conflicts.length)
+        reject({
+            class: "conflict",
+            message: `TODO owner correction requires complete one-to-one evidence; found ${conflicts.length} conflicting claim${conflicts.length === 1 ? "" : "s"}`,
+            violations: [...conflicts.slice(0, DIAGNOSTIC_LIMIT), ...(conflicts.length > DIAGNOSTIC_LIMIT ? [`${conflicts.length - DIAGNOSTIC_LIMIT} additional conflicts omitted`] : [])],
+            diagnosis: {
+                counts: { matched: records.size, converted: legacy.length, retained: 0, duplicate: 0, stale, conflicting: conflicts.length },
+                items,
+                omitted_count: Math.max(0, evidence.owners.length - items.length),
+                conflicts_omitted_count: Math.max(0, conflicts.length - DIAGNOSTIC_LIMIT),
+            },
+            recovery: `Correct every id/source_line claim and rerun exactly '${TODO_OWNER_CORRECTION_PREVIEW_COMMAND}'; no state was changed.`,
+        });
+    const rendered = `${markdown.split(/\r?\n/).map((line, index) => replacements.get(index) ?? line).join("\n").replace(/\n*$/, "")}\n`;
+    return {
+        records,
+        rendered,
+        diagnosis: {
+            counts: { matched: records.size, converted: legacy.length, retained: 0, duplicate: 0, stale, conflicting: 0 },
+            items,
+            omitted_count: Math.max(0, evidence.owners.length - items.length),
+        },
+    };
+}

package/dist/state/todoReconciliationTransaction.js

@@ -99,7 +99,7 @@ function parseJournal(bytes, fileName) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         invalidJournal("TODO reconciliation journal is not a mapping");
     const value = parsed;
-    const expectedKeys = ["schema_version", "id", "public_path", "mapping_sha256", "targets", ...(value.create === undefined ? [] : ["create"]), ...(value.activation_effect_sha256 === undefined ? [] : ["activation_effect_sha256"])].sort().join(",");
+    const expectedKeys = ["schema_version", "id", "public_path", "mapping_sha256", "targets", ...(value.create === undefined ? [] : ["create"]), ...(value.activation_effect_sha256 === undefined ? [] : ["activation_effect_sha256"]), ...(value.owner_mapping_sha256 === undefined ? [] : ["owner_mapping_sha256"])].sort().join(",");
     if (Object.keys(value).sort().join(",") !== expectedKeys
         || value.schema_version !== VERSION
         || typeof value.id !== "string"
@@ -113,6 +113,8 @@ function parseJournal(bytes, fileName) {
         invalidJournal("TODO reconciliation journal is malformed");
     if (value.activation_effect_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.activation_effect_sha256))
         invalidJournal("TODO reconciliation journal has an invalid activation effect authorization");
+    if (value.owner_mapping_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.owner_mapping_sha256))
+        invalidJournal("TODO reconciliation journal has an invalid owner-mapping authorization");
     if (value.create !== undefined && (!value.create
         || typeof value.create !== "object"
         || Array.isArray(value.create)
@@ -140,15 +142,17 @@ function parseJournal(bytes, fileName) {
     }
     const body = value.targets;
     const activates = body.some((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH);
-    if (!activates && value.activation_effect_sha256 !== undefined)
+    if (!activates && (value.activation_effect_sha256 !== undefined || value.owner_mapping_sha256 !== undefined))
         invalidJournal("TODO reconciliation journal effect authorization has no activation target");
+    if (value.owner_mapping_sha256 !== undefined && value.activation_effect_sha256 === undefined)
+        invalidJournal("TODO reconciliation journal owner-mapping authorization has no effect authorization");
     const inferredCreate = createReceiptFromTargets(body);
     if (value.create && (!inferredCreate
         || value.create.created_id !== inferredCreate.created_id
         || value.create.request_sha256 !== inferredCreate.request_sha256))
         invalidJournal("TODO reconciliation create receipt does not match its canonical entity target");
-    const identity = value.create || value.activation_effect_sha256
-        ? { ...(value.create ? { create: value.create } : {}), ...(value.activation_effect_sha256 ? { activation_effect_sha256: value.activation_effect_sha256 } : {}), targets: body }
+    const identity = value.create || value.activation_effect_sha256 || value.owner_mapping_sha256
+        ? { ...(value.create ? { create: value.create } : {}), ...(value.activation_effect_sha256 ? { activation_effect_sha256: value.activation_effect_sha256 } : {}), ...(value.owner_mapping_sha256 ? { owner_mapping_sha256: value.owner_mapping_sha256 } : {}), targets: body }
         : body;
     const expectedId = createHash("sha256").update(canonicalRecordJson(identity)).digest("hex").slice(0, 24);
     if (value.id !== expectedId || (fileName !== undefined && fileName !== `${value.id}.json`)) {
@@ -454,6 +458,12 @@ export function recoverTodoReconciliation(context, sourceRoot, binding, options
                 message: "pending TODO activation does not match the authorized preview effect",
                 recovery: "Retry the exact activation apply command returned by the original preview; no transaction target bytes were changed.",
             });
+        if (journal.owner_mapping_sha256 && options.ownerMappingSha256 !== journal.owner_mapping_sha256)
+            reject({
+                class: "conflict",
+                message: "pending TODO owner correction does not match the supplied owner mapping",
+                recovery: "Retry the exact correction input and apply command returned by the original preview; no transaction target bytes were changed.",
+            });
         options.beforeRecovery?.(journal.targets.map((target) => ({
             path: target.path,
             before: target.before === null ? null : decode(target.before),
@@ -498,10 +508,12 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         || Number(left.path === binding.publicPath) - Number(right.path === binding.publicPath)
         || left.path.localeCompare(right.path));
     const body = normalized.map((target) => ({ path: target.path, before: target.before === null ? null : encode(target.before), after: encode(target.after) }));
-    if (options.activationEffectSha256 && !normalized.some((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH))
+    if ((options.activationEffectSha256 || options.ownerMappingSha256) && !normalized.some((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH))
         reject({ class: "schema_violation", message: "TODO activation authorization requires its activation target", recovery: "Recompute the complete activation target set from a fresh dry-run; no state was changed." });
-    const identity = options.create || options.activationEffectSha256
-        ? { ...(options.create ? { create: options.create } : {}), ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}), targets: body }
+    if (options.ownerMappingSha256 && !options.activationEffectSha256)
+        reject({ class: "schema_violation", message: "TODO owner-mapping authorization requires its effect authorization", recovery: "Recompute the complete owner correction target set from a fresh dry-run; no state was changed." });
+    const identity = options.create || options.activationEffectSha256 || options.ownerMappingSha256
+        ? { ...(options.create ? { create: options.create } : {}), ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}), ...(options.ownerMappingSha256 ? { owner_mapping_sha256: options.ownerMappingSha256 } : {}), targets: body }
         : body;
     const id = createHash("sha256").update(canonicalRecordJson(identity)).digest("hex").slice(0, 24);
     if (!normalized.length)
@@ -533,6 +545,7 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         mapping_sha256: binding.mappingSha256,
         ...(options.create ? { create: options.create } : {}),
         ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}),
+        ...(options.ownerMappingSha256 ? { owner_mapping_sha256: options.ownerMappingSha256 } : {}),
         targets: body,
     };
     const bytes = `${JSON.stringify(journal)}\n`;