brainclaw 1.26.2 → 1.28.0

package/dist/core/loops/attempt-rollout.js

@@ -0,0 +1,404 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { memoryDir, writeFileAtomic } from '../io.js';
+import { nowISO } from '../ids.js';
+import { fingerprintPublicKeyPem } from '../agent-registry.js';
+import { AuthorityHomeSchema } from './attempt-generations.js';
+/**
+ * Two-release activation guard for AttemptAuthority v2.
+ *
+ * Release A publishes one immutable membership guard and one independently
+ * signed ACK per writer. ACKs are deliberately separate cells: writers may
+ * prepare/sign/publish them in parallel without contending on a shared JSON
+ * document. Release B is enabled by one immutable activation CAS only after all
+ * non-revoked participants acknowledged the same guard digest.
+ */
+export const ATTEMPT_AUTHORITY_WRITER_VERSION = 2;
+export const ATTEMPT_AUTHORITY_READER_VERSION = 2;
+const ROLLOUT_SCHEMA_VERSION = 1;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const AttemptWriterParticipantSchema = z.object({
+    writer_id: z.string().regex(SAFE_ID),
+    public_key_pem: z.string().min(1),
+    key_fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    status: z.enum(['active', 'revoked']).default('active'),
+}).strict();
+export const AttemptRolloutGuardSchema = z.object({
+    schema_version: z.literal(ROLLOUT_SCHEMA_VERSION),
+    document_kind: z.literal('attempt_authority_writer_guard'),
+    membership_epoch: z.number().int().positive(),
+    minimum_writer_version: z.number().int().positive(),
+    minimum_reader_version: z.number().int().positive(),
+    authority_home: AuthorityHomeSchema,
+    participants: z.array(AttemptWriterParticipantSchema).min(1),
+    previous_activation_digest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    prepared_by: z.string().min(1),
+    prepared_at: z.string().min(1),
+}).strict();
+const AttemptRolloutAckUnsignedSchema = z.object({
+    schema_version: z.literal(ROLLOUT_SCHEMA_VERSION),
+    document_kind: z.literal('attempt_authority_writer_ack'),
+    membership_epoch: z.number().int().positive(),
+    writer_id: z.string().regex(SAFE_ID),
+    writer_version: z.number().int().positive(),
+    reader_version: z.number().int().positive(),
+    guard_digest: z.string().regex(/^[a-f0-9]{64}$/),
+    key_fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    acknowledged_at: z.string().min(1),
+}).strict();
+export const AttemptRolloutAckSchema = AttemptRolloutAckUnsignedSchema.extend({
+    signature: z.string().min(1),
+}).strict();
+export const AttemptRolloutActivationSchema = z.object({
+    schema_version: z.literal(ROLLOUT_SCHEMA_VERSION),
+    document_kind: z.literal('attempt_authority_activation'),
+    membership_epoch: z.number().int().positive(),
+    guard_digest: z.string().regex(/^[a-f0-9]{64}$/),
+    ack_digests: z.record(z.string().regex(SAFE_ID), z.string().regex(/^[a-f0-9]{64}$/)),
+    authority_home: AuthorityHomeSchema,
+    activated_by: z.string().min(1),
+    activated_at: z.string().min(1),
+}).strict();
+export class AttemptRolloutError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AttemptRolloutError';
+    }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonical(child)]));
+}
+function digest(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+}
+export function attemptRolloutGuardDigest(guard) {
+    return digest(AttemptRolloutGuardSchema.parse(guard));
+}
+export function attemptRolloutAckDigest(ack) {
+    return digest(AttemptRolloutAckSchema.parse(ack));
+}
+export function attemptRolloutActivationDigest(activation) {
+    return digest(AttemptRolloutActivationSchema.parse(activation));
+}
+function rolloutRoot(cwd) {
+    return path.join(memoryDir(cwd), 'loops', 'attempt-authority-v2', 'rollout');
+}
+function epochDir(cwd, membershipEpoch) {
+    return path.join(rolloutRoot(cwd), `epoch-${membershipEpoch}`);
+}
+export function attemptRolloutGuardPath(cwd, membershipEpoch) {
+    return path.join(epochDir(cwd, membershipEpoch), 'guard.json');
+}
+export function attemptRolloutAckPath(cwd, membershipEpoch, writerId) {
+    if (!SAFE_ID.test(writerId))
+        throw new Error(`unsafe writer_id: ${writerId}`);
+    return path.join(epochDir(cwd, membershipEpoch), 'acks', `${writerId}.json`);
+}
+export function attemptRolloutActivationPath(cwd, membershipEpoch) {
+    return path.join(epochDir(cwd, membershipEpoch), 'active.decision.json');
+}
+const HARDLINK_UNSUPPORTED = new Set(['ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV', 'EINVAL', 'EPERM', 'EACCES']);
+function readCell(filePath, schema) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return schema.parse(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+    }
+    catch (error) {
+        throw new AttemptRolloutError('corrupt_rollout_cell', `rollout cell is corrupt: ${filePath} (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+function publishCell(filePath, value, schema) {
+    const cell = schema.parse(value);
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temp, 'wx');
+    try {
+        const bytes = Buffer.from(`${JSON.stringify(cell, null, 2)}\n`, 'utf8');
+        let offset = 0;
+        while (offset < bytes.length)
+            offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.linkSync(temp, filePath);
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch { /* orphan temp is non-authoritative */ }
+        return { won: true, cell };
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch { /* best effort */ }
+        const code = error.code;
+        if (code === 'EEXIST') {
+            const incumbent = readCell(filePath, schema);
+            if (!incumbent)
+                throw new AttemptRolloutError('corrupt_rollout_cell', `rollout incumbent vanished: ${filePath}`);
+            return { won: false, cell: incumbent };
+        }
+        if (code && HARDLINK_UNSUPPORTED.has(code)) {
+            throw new AttemptRolloutError('hardlink_unsupported', `filesystem cannot publish rollout cells with hardlink CAS (${code})`);
+        }
+        throw error;
+    }
+}
+function same(left, right) {
+    return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}
+export function prepareAttemptAuthorityRollout(cwd, input) {
+    const participants = input.participants.map((participant) => {
+        const parsed = AttemptWriterParticipantSchema.parse(participant);
+        if (fingerprintPublicKeyPem(parsed.public_key_pem) !== parsed.key_fingerprint) {
+            throw new AttemptRolloutError('bad_signature', `public key fingerprint mismatch for ${parsed.writer_id}`);
+        }
+        return parsed;
+    });
+    if (new Set(participants.map((participant) => participant.writer_id)).size !== participants.length) {
+        throw new AttemptRolloutError('membership_mismatch', 'rollout participants contain duplicate writer_id values');
+    }
+    const guard = AttemptRolloutGuardSchema.parse({
+        schema_version: ROLLOUT_SCHEMA_VERSION,
+        document_kind: 'attempt_authority_writer_guard',
+        membership_epoch: input.membership_epoch,
+        minimum_writer_version: input.minimum_writer_version ?? ATTEMPT_AUTHORITY_WRITER_VERSION,
+        minimum_reader_version: input.minimum_reader_version ?? ATTEMPT_AUTHORITY_READER_VERSION,
+        authority_home: input.authority_home,
+        participants,
+        previous_activation_digest: input.previous_activation_digest,
+        prepared_by: input.prepared_by,
+        prepared_at: input.prepared_at ?? nowISO(),
+    });
+    const current = resolveActiveAttemptRollout(cwd);
+    if (current) {
+        if (guard.membership_epoch <= current.guard.membership_epoch) {
+            throw new AttemptRolloutError('membership_mismatch', 'new membership epoch must exceed the active epoch');
+        }
+        if (guard.previous_activation_digest !== attemptRolloutActivationDigest(current.activation)) {
+            throw new AttemptRolloutError('membership_mismatch', 'new guard does not chain from the active rollout');
+        }
+        if (!same(guard.authority_home, current.guard.authority_home)) {
+            throw new AttemptRolloutError('authority_home_mismatch', 'membership rollover cannot change authority_home without an explicit transfer protocol');
+        }
+    }
+    else if (guard.membership_epoch !== 1 || guard.previous_activation_digest !== undefined) {
+        throw new AttemptRolloutError('membership_mismatch', 'the first rollout guard must be membership epoch 1 without a predecessor');
+    }
+    const published = publishCell(attemptRolloutGuardPath(cwd, guard.membership_epoch), guard, AttemptRolloutGuardSchema);
+    if (!same(published.cell, guard)) {
+        throw new AttemptRolloutError('membership_mismatch', `a different guard already exists for epoch ${guard.membership_epoch}`);
+    }
+    return published.cell;
+}
+function ackSigningBytes(ack) {
+    return Buffer.from(JSON.stringify(canonical(AttemptRolloutAckUnsignedSchema.parse(ack))), 'utf8');
+}
+export function publishAttemptRolloutAck(cwd, input) {
+    const guard = readCell(attemptRolloutGuardPath(cwd, input.membership_epoch), AttemptRolloutGuardSchema);
+    if (!guard)
+        throw new AttemptRolloutError('not_prepared', `rollout epoch ${input.membership_epoch} is not prepared`);
+    const participant = guard.participants.find((candidate) => candidate.writer_id === input.writer_id && candidate.status === 'active');
+    if (!participant)
+        throw new AttemptRolloutError('participant_unknown', `writer ${input.writer_id} is not active in rollout epoch ${input.membership_epoch}`);
+    if (input.writer_version < guard.minimum_writer_version) {
+        throw new AttemptRolloutError('writer_too_old', `writer ${input.writer_id} version ${input.writer_version} < ${guard.minimum_writer_version}`);
+    }
+    const readerVersion = input.reader_version ?? ATTEMPT_AUTHORITY_READER_VERSION;
+    if (readerVersion < guard.minimum_reader_version) {
+        throw new AttemptRolloutError('writer_too_old', `writer ${input.writer_id} reader version ${readerVersion} < ${guard.minimum_reader_version}`);
+    }
+    const privateKey = crypto.createPrivateKey(input.private_key_pem);
+    const publicKeyPem = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' }).toString();
+    if (fingerprintPublicKeyPem(publicKeyPem) !== participant.key_fingerprint) {
+        throw new AttemptRolloutError('bad_signature', `private key does not belong to writer ${input.writer_id}`);
+    }
+    const unsigned = AttemptRolloutAckUnsignedSchema.parse({
+        schema_version: ROLLOUT_SCHEMA_VERSION,
+        document_kind: 'attempt_authority_writer_ack',
+        membership_epoch: guard.membership_epoch,
+        writer_id: input.writer_id,
+        writer_version: input.writer_version,
+        reader_version: readerVersion,
+        guard_digest: attemptRolloutGuardDigest(guard),
+        key_fingerprint: participant.key_fingerprint,
+        acknowledged_at: input.acknowledged_at ?? nowISO(),
+    });
+    const ack = AttemptRolloutAckSchema.parse({
+        ...unsigned,
+        signature: crypto.sign(null, ackSigningBytes(unsigned), privateKey).toString('base64url'),
+    });
+    const published = publishCell(attemptRolloutAckPath(cwd, guard.membership_epoch, input.writer_id), ack, AttemptRolloutAckSchema);
+    if (!same(published.cell, ack)) {
+        throw new AttemptRolloutError('membership_mismatch', `writer ${input.writer_id} already acknowledged with different bytes`);
+    }
+    return published.cell;
+}
+function verifyAck(guard, ack) {
+    const participant = guard.participants.find((candidate) => candidate.writer_id === ack.writer_id && candidate.status === 'active');
+    if (!participant)
+        throw new AttemptRolloutError('participant_unknown', `ack writer ${ack.writer_id} is not active`);
+    if (ack.membership_epoch !== guard.membership_epoch || ack.guard_digest !== attemptRolloutGuardDigest(guard)) {
+        throw new AttemptRolloutError('membership_mismatch', `ack ${ack.writer_id} targets a different guard`);
+    }
+    if (ack.writer_version < guard.minimum_writer_version) {
+        throw new AttemptRolloutError('writer_too_old', `ack ${ack.writer_id} advertises writer version ${ack.writer_version}`);
+    }
+    if (ack.reader_version < guard.minimum_reader_version) {
+        throw new AttemptRolloutError('writer_too_old', `ack ${ack.writer_id} reader version ${ack.reader_version} < ${guard.minimum_reader_version}`);
+    }
+    const { signature, ...unsigned } = ack;
+    const valid = crypto.verify(null, ackSigningBytes(AttemptRolloutAckUnsignedSchema.parse(unsigned)), crypto.createPublicKey(participant.public_key_pem), Buffer.from(signature, 'base64url'));
+    if (!valid || participant.key_fingerprint !== ack.key_fingerprint) {
+        throw new AttemptRolloutError('bad_signature', `ack signature is invalid for ${ack.writer_id}`);
+    }
+}
+export function activateAttemptAuthorityV2(cwd, membershipEpoch, activatedBy, activatedAt = nowISO()) {
+    const guard = readCell(attemptRolloutGuardPath(cwd, membershipEpoch), AttemptRolloutGuardSchema);
+    if (!guard)
+        throw new AttemptRolloutError('not_prepared', `rollout epoch ${membershipEpoch} is not prepared`);
+    const ackDigests = {};
+    for (const participant of guard.participants.filter((candidate) => candidate.status === 'active')) {
+        const ack = readCell(attemptRolloutAckPath(cwd, membershipEpoch, participant.writer_id), AttemptRolloutAckSchema);
+        if (!ack)
+            throw new AttemptRolloutError('not_active', `writer ${participant.writer_id} has not acknowledged rollout epoch ${membershipEpoch}`);
+        verifyAck(guard, ack);
+        ackDigests[participant.writer_id] = attemptRolloutAckDigest(ack);
+    }
+    const activation = AttemptRolloutActivationSchema.parse({
+        schema_version: ROLLOUT_SCHEMA_VERSION,
+        document_kind: 'attempt_authority_activation',
+        membership_epoch: membershipEpoch,
+        guard_digest: attemptRolloutGuardDigest(guard),
+        ack_digests: ackDigests,
+        authority_home: guard.authority_home,
+        activated_by: activatedBy,
+        activated_at: activatedAt,
+    });
+    const published = publishCell(attemptRolloutActivationPath(cwd, membershipEpoch), activation, AttemptRolloutActivationSchema);
+    if (!same(published.cell, activation)) {
+        throw new AttemptRolloutError('membership_mismatch', `rollout epoch ${membershipEpoch} was activated with different acknowledgements`);
+    }
+    return published.cell;
+}
+export function resolveActiveAttemptRollout(cwd) {
+    const root = rolloutRoot(cwd);
+    if (!fs.existsSync(root))
+        return undefined;
+    const epochs = fs.readdirSync(root)
+        .map((name) => /^epoch-(\d+)$/.exec(name)?.[1])
+        .filter((value) => value !== undefined)
+        .map(Number)
+        .filter(Number.isSafeInteger)
+        .sort((left, right) => left - right);
+    let latest;
+    for (const membershipEpoch of epochs) {
+        const activation = readCell(attemptRolloutActivationPath(cwd, membershipEpoch), AttemptRolloutActivationSchema);
+        if (!activation)
+            continue;
+        const guard = readCell(attemptRolloutGuardPath(cwd, membershipEpoch), AttemptRolloutGuardSchema);
+        if (!guard || activation.guard_digest !== attemptRolloutGuardDigest(guard) || !same(activation.authority_home, guard.authority_home)) {
+            throw new AttemptRolloutError('corrupt_rollout_cell', `activation/guard mismatch at epoch ${membershipEpoch}`);
+        }
+        if (!latest) {
+            if (guard.membership_epoch !== 1 || guard.previous_activation_digest !== undefined) {
+                throw new AttemptRolloutError('corrupt_rollout_cell', 'activation chain does not start at membership epoch 1');
+            }
+        }
+        else {
+            if (guard.previous_activation_digest !== attemptRolloutActivationDigest(latest.activation)) {
+                throw new AttemptRolloutError('corrupt_rollout_cell', `activation epoch ${membershipEpoch} is not chained to its predecessor`);
+            }
+            if (!same(guard.authority_home, latest.guard.authority_home)) {
+                throw new AttemptRolloutError('authority_home_mismatch', 'activation chain changes authority_home without transfer');
+            }
+        }
+        for (const participant of guard.participants.filter((candidate) => candidate.status === 'active')) {
+            const ack = readCell(attemptRolloutAckPath(cwd, membershipEpoch, participant.writer_id), AttemptRolloutAckSchema);
+            if (!ack)
+                throw new AttemptRolloutError('corrupt_rollout_cell', `activated writer ${participant.writer_id} has no ACK`);
+            verifyAck(guard, ack);
+            if (activation.ack_digests[participant.writer_id] !== attemptRolloutAckDigest(ack)) {
+                throw new AttemptRolloutError('corrupt_rollout_cell', `activation ACK digest mismatch for ${participant.writer_id}`);
+            }
+        }
+        latest = { guard, activation };
+    }
+    return latest;
+}
+export function assertAttemptAuthorityV2Writable(cwd, localAuthorityHome, writerVersion = ATTEMPT_AUTHORITY_WRITER_VERSION, writerId, readerVersion = ATTEMPT_AUTHORITY_READER_VERSION) {
+    const active = resolveActiveAttemptRollout(cwd);
+    if (!active)
+        throw new AttemptRolloutError('not_active', 'AttemptAuthority v2 has no activated writer guard');
+    if (writerVersion < active.guard.minimum_writer_version) {
+        throw new AttemptRolloutError('writer_too_old', `writer version ${writerVersion} < ${active.guard.minimum_writer_version}`);
+    }
+    if (readerVersion < active.guard.minimum_reader_version) {
+        throw new AttemptRolloutError('writer_too_old', `reader version ${readerVersion} < ${active.guard.minimum_reader_version}`);
+    }
+    const participant = writerId
+        ? active.guard.participants.find((candidate) => candidate.writer_id === writerId && candidate.status === 'active')
+        : undefined;
+    if (!participant || active.activation.ack_digests[participant.writer_id] === undefined) {
+        throw new AttemptRolloutError('participant_unknown', `writer ${writerId ?? '(missing)'} is not active in the activated membership`);
+    }
+    if (!same(AuthorityHomeSchema.parse(localAuthorityHome), active.guard.authority_home)) {
+        throw new AttemptRolloutError('authority_home_mismatch', 'this store/device is not the activated authority_home');
+    }
+    return active;
+}
+function localIdentityPath(cwd, options = {}) {
+    const root = options.identity_root
+        ?? process.env.BRAINCLAW_AUTHORITY_IDENTITY_ROOT
+        ?? path.join(os.homedir(), '.brainclaw', 'store-instances');
+    let canonicalPath;
+    try {
+        canonicalPath = fs.realpathSync.native(cwd);
+    }
+    catch {
+        canonicalPath = path.resolve(cwd);
+    }
+    const locator = crypto.createHash('sha256').update(process.platform === 'win32' ? canonicalPath.toLowerCase() : canonicalPath).digest('hex');
+    return path.join(root, `${locator}.json`);
+}
+export function ensureLocalAuthorityHome(cwd, options = {}) {
+    const filePath = localIdentityPath(cwd, options);
+    if (fs.existsSync(filePath)) {
+        const existing = AuthorityHomeSchema.parse(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+        if (options.device_id && existing.device_id !== options.device_id) {
+            throw new AttemptRolloutError('authority_home_mismatch', `local authority identity is bound to ${existing.device_id}, not paired device ${options.device_id}`);
+        }
+        return existing;
+    }
+    const identity = AuthorityHomeSchema.parse({
+        store_instance_id: `sti_${crypto.randomUUID()}`,
+        device_id: options.device_id ?? `dev_${crypto.randomUUID()}`,
+    });
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileAtomic(filePath, `${JSON.stringify(identity, null, 2)}\n`);
+    return identity;
+}
+export function readLocalAuthorityHome(cwd, options = {}) {
+    const filePath = localIdentityPath(cwd, options);
+    if (!fs.existsSync(filePath))
+        return undefined;
+    return AuthorityHomeSchema.parse(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+}
+//# sourceMappingURL=attempt-rollout.js.map

package/dist/core/loops/attempt-takeover.js

@@ -0,0 +1,155 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { ensureAgentRunProjection, loadAgentRun, transitionAgentRun } from '../agentruns.js';
+import { loadAssignment } from '../assignments.js';
+import { createRuntimeEvent } from '../events.js';
+import { nowISO } from '../ids.js';
+import { prepareAttemptTakeoverV2 } from './attempt-authority.js';
+import { generationDigest } from './attempt-generations.js';
+import { commitViaIntent } from './commit-intent.js';
+import { evidenceDigest } from './evidence.js';
+import { withLoopLock } from './lock.js';
+import { getReservation } from './attempt-reservation.js';
+import { getLoop, listLoopEvents } from './store.js';
+/**
+ * Operator/engine takeover transaction.
+ *
+ * Under the loop lock it publishes close(epoch) and the causal LoopEvent. The
+ * immutable close cell remains the authority; AgentRun/RuntimeEvent/head are
+ * replayable projections applied after the lock is released. The successor is
+ * ARMED but not crossed — the normal worker dispatch path must project then win
+ * launch(next epoch) immediately before spawn.
+ */
+export function takeoverLoopAttempt(input) {
+    if (!fs.existsSync(input.next_workspace_path) || !fs.statSync(input.next_workspace_path).isDirectory()) {
+        throw new Error(`takeover workspace must already exist as an isolated directory: ${input.next_workspace_path}`);
+    }
+    const authorityActor = input.actor_id ?? input.actor;
+    const transaction = withLoopLock({
+        cwd: input.cwd,
+        intent: 'attempt-takeover',
+        agentId: authorityActor,
+        scope: { kind: 'loop', loopId: input.loop_id },
+        work: () => {
+            const loop = getLoop(input.loop_id, input.cwd);
+            if (!loop || loop.status !== 'open')
+                throw new Error(`loop ${input.loop_id} is not open`);
+            if (loop.created_by !== authorityActor) {
+                throw new Error(`attempt takeover requires loop coordinator ${loop.created_by}; caller is ${authorityActor}`);
+            }
+            const slot = loop.slots.find((candidate) => candidate.slot_id === input.slot_id);
+            if (!slot)
+                throw new Error(`slot ${input.slot_id} not found in loop ${input.loop_id}`);
+            const reservation = getReservation(input.turn_id, input.cwd);
+            if (!reservation || reservation.loop_id !== loop.id || reservation.slot_id !== slot.slot_id) {
+                throw new Error(`turn ${input.turn_id} does not own ${loop.id}/${slot.slot_id}`);
+            }
+            if (slot.current_turn_id !== input.turn_id || slot.assignment_id !== reservation.child_ids.assignment_id) {
+                throw new Error(`slot ${slot.slot_id} is no longer bound to turn ${input.turn_id}`);
+            }
+            const takeover = prepareAttemptTakeoverV2({ ...input, actor: authorityActor });
+            const duplicate = listLoopEvents(loop.id, input.cwd).some((event) => event.kind === 'attempt_generation_changed'
+                && event.turn_id === input.turn_id
+                && event.to_epoch === takeover.next_generation.attempt_epoch
+                && event.to_run_id === takeover.next_generation.run_id);
+            if (duplicate)
+                return { loop, takeover, reservation };
+            const now = nowISO();
+            const mutationId = crypto.randomUUID();
+            const event = {
+                event_id: crypto.randomUUID(),
+                loop_id: loop.id,
+                seq: loop.version + 1,
+                at: now,
+                by: authorityActor,
+                mutation_id: mutationId,
+                kind: 'attempt_generation_changed',
+                slot_id: slot.slot_id,
+                turn_id: input.turn_id,
+                assignment_id: takeover.next_generation.assignment_id,
+                from_epoch: takeover.previous_generation.attempt_epoch,
+                to_epoch: takeover.next_generation.attempt_epoch,
+                from_run_id: takeover.previous_generation.run_id,
+                to_run_id: takeover.next_generation.run_id,
+                close_digest: evidenceDigest(takeover.close_cell),
+                cause: input.cause,
+            };
+            const next = {
+                ...loop,
+                version: loop.version + 1,
+                mutation_id: mutationId,
+                updated_at: now,
+            };
+            commitViaIntent({ loop_id: loop.id, base_version: loop.version, events: [event], thread_snapshot: next }, input.cwd);
+            return { loop: next, takeover, reservation };
+        },
+    });
+    const { takeover, reservation } = transaction;
+    const assignment = loadAssignment(takeover.next_generation.assignment_id, input.cwd);
+    const previousRun = loadAgentRun(takeover.previous_generation.run_id, input.cwd);
+    if (previousRun && !['completed', 'failed', 'cancelled', 'timed_out', 'interrupted'].includes(previousRun.status)) {
+        try {
+            transitionAgentRun(previousRun.id, 'interrupted', {
+                actor: input.actor,
+                status_reason: `fenced by ${input.mode ?? 'takeover'} to epoch ${takeover.next_generation.attempt_epoch}`,
+                allow_fenced_projection: true,
+            }, input.cwd);
+        }
+        catch { /* immutable close cell already fences the old run */ }
+    }
+    ensureAgentRunProjection({
+        id: takeover.next_generation.run_id,
+        short_label: takeover.next_generation.run_id,
+        assignment_id: takeover.next_generation.assignment_id,
+        claim_id: reservation.claim_id,
+        attempt_index: takeover.next_generation.attempt_epoch + 1,
+        agent: reservation.agent,
+        agent_id: reservation.agent_id,
+        transport: 'cli_spawn',
+        status: 'created',
+        scope: assignment?.scope ?? reservation.execution_contract?.workspace_policy.scope ?? reservation.cwd,
+        description: assignment?.description ?? `Attempt generation ${takeover.next_generation.attempt_epoch} for ${input.turn_id}`,
+        worktree_path: takeover.next_generation.workspace_path,
+        execution_contract_ref: takeover.execution_contract_ref,
+        capability_snapshot: reservation.capability_snapshot,
+        tags: ['turn-owned', 'loop', 'attempt-takeover', `attempt-generation:${takeover.next_generation.attempt_epoch}`],
+    }, input.cwd);
+    try {
+        createRuntimeEvent({
+            agent: input.actor,
+            event_type: 'attempt_takeover',
+            text: `Attempt ${input.turn_id} moved from epoch ${takeover.previous_generation.attempt_epoch} to ${takeover.next_generation.attempt_epoch}`,
+            tags: ['loops', 'attempt-authority-v2', input.mode ?? 'takeover'],
+            assignment_id: takeover.next_generation.assignment_id,
+            run_id: takeover.next_generation.run_id,
+            turn_id: input.turn_id,
+            nonce: takeover.next_generation.launch_nonce,
+            attempt_epoch: takeover.next_generation.attempt_epoch,
+            workspace_digest: takeover.next_generation.workspace_digest,
+            status: 'created',
+            status_reason: input.cause,
+            metadata: {
+                previous_run_id: takeover.previous_generation.run_id,
+                generation_digest: generationDigest(takeover.next_generation),
+                close_digest: evidenceDigest(takeover.close_cell),
+                liveness_evidence: input.liveness_evidence,
+                external_effect_policy: input.external_effect_policy,
+            },
+        }, input.cwd);
+    }
+    catch { /* immutable close cell + LoopEvent are sufficient for recovery */ }
+    return {
+        loop: transaction.loop,
+        turn_id: input.turn_id,
+        assignment_id: takeover.next_generation.assignment_id,
+        previous_run_id: takeover.previous_generation.run_id,
+        run_id: takeover.next_generation.run_id,
+        attempt_epoch: takeover.next_generation.attempt_epoch,
+        launch_nonce: takeover.next_generation.launch_nonce,
+        workspace_digest: takeover.next_generation.workspace_digest,
+        execution_contract_hash: takeover.execution_contract_ref.hash,
+        won_close: takeover.won,
+        spawn_authority: false,
+    };
+}
+//# sourceMappingURL=attempt-takeover.js.map

package/dist/core/loops/bootstrap-acquire.js

@@ -21,7 +21,7 @@ import { acquireClaimScope, listClaims, releaseClaim } from '../claims.js';
 import { buildSurveySignalsBaseline } from './hooks/survey-signals-baseline.js';
 import { BOOTSTRAP_PRESET } from './presets/bootstrap.js';
 import { listLoops, openLoop } from './store.js';
-import { add_artifact } from './verbs.js';
+import { addArtifactWithEvidence } from './verbs.js';
 export class BootstrapCoordinationInProgressError extends Error {
     blockingClaimId;
     constructor(blockingClaimId) {
@@ -192,14 +192,18 @@ export function acquireBootstrapLoop(opts, cwd) {
         // failure must never block opening the loop.
         try {
             const baseline = buildSurveySignalsBaseline(cwd ?? process.cwd());
-            loop = add_artifact({
+            loop = addArtifactWithEvidence({
                 id: loop.id,
                 actor: opts.created_by ?? opts.agent_id ?? opts.actor,
+                evidence_context: {
+                    channel: 'system_hook',
+                    producer_kind: 'engine',
+                    producer_id: 'brainclaw-scanner',
+                },
                 artifact: {
                     phase: 'survey',
                     type: 'signals_baseline',
                     body: JSON.stringify(baseline),
-                    produced_by: 'brainclaw-scanner',
                 },
             }, cwd);
             warnings.push('survey baseline attached (artifact type signals_baseline, produced by the deterministic scanner) — enrich it into your signals_report instead of re-scanning the repo from scratch.');

package/dist/core/loops/brief-assembly.js

@@ -45,9 +45,9 @@ const LOOP_INTERNAL_CATEGORIES = new Set([
     'synthesis_artifact',
 ]);
 export function buildIdeationBrief(input) {
-    const { thread, slotRole, memoryProvider, maxChars = DEFAULT_MAX_CHARS, topKPerCategory = DEFAULT_TOP_K_PER_CATEGORY, } = input;
+    const { thread, slotRole, memoryProvider, maxChars = DEFAULT_MAX_CHARS, topKPerCategory = DEFAULT_TOP_K_PER_CATEGORY, seedText, scopeHints = [], } = input;
     const proposal = findProposalArtifact(thread);
-    const proposalText = proposal?.body?.trim() ?? '(no proposal seed found)';
+    const proposalText = seedText?.trim() || proposal?.body?.trim() || '(no proposal seed found)';
     // Resolve which memory categories the current phase wants. If the
     // current phase has no context_filter, fall back to '*' (full bundle).
     const currentPhaseDef = thread.phases.find((p) => p.name === thread.current_phase);
@@ -57,7 +57,7 @@ export function buildIdeationBrief(input) {
     const fetchedItemsByCategory = new Map();
     const categoriesUsed = [];
     for (const category of userFacingCategories) {
-        const items = memoryProvider.fetch(category, proposalText, topKPerCategory);
+        const items = scopeMemoryItems(memoryProvider.fetch(category, `${proposalText} ${scopeHints.join(' ')}`.trim(), topKPerCategory), scopeHints);
         if (items.length > 0) {
             fetchedItemsByCategory.set(category, items);
             categoriesUsed.push(category);
@@ -116,7 +116,7 @@ function expandUserFacingCategories(requested) {
 }
 function renderHeader(thread, slotRole, phase) {
     const lines = [
-        `# ideation_loop brief`,
+        `# ${thread.kind}_loop brief`,
         `loop: ${thread.id}`,
         `phase: ${phase}`,
         `iteration: ${thread.iteration_count}`,
@@ -127,6 +127,23 @@ function renderHeader(thread, slotRole, phase) {
         lines.push(`goal: ${thread.goal}`);
     return lines.join('\n');
 }
+function normalizeScope(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+}
+/** Keep project-wide memories and memories whose related_paths overlap this lane. */
+function scopeMemoryItems(items, scopeHints) {
+    const scopes = scopeHints.map(normalizeScope).filter(Boolean);
+    if (scopes.length === 0)
+        return items;
+    return items.filter((item) => {
+        if (!item.relatedPaths || item.relatedPaths.length === 0)
+            return true;
+        return item.relatedPaths.some((related) => {
+            const path = normalizeScope(related);
+            return scopes.some((scope) => path.startsWith(scope) || scope.startsWith(path));
+        });
+    });
+}
 function renderProposalBlock(proposalText) {
     return `## proposal\n\n${proposalText}`;
 }