@orkastery/cli 0.2.0 → 0.4.1

package/dist/maestro-authority.js

@@ -0,0 +1,152 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireSessionReviewRuntime = requireSessionReviewRuntime;
+exports.parseSessionReviewBinding = parseSessionReviewBinding;
+exports.verifySessionReview = verifySessionReview;
+exports.verifyCompletedSessionReview = verifyCompletedSessionReview;
+/** Independência vem do despacho persistido, nunca do nome do runtime ou do relato. */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const thread_1 = require("./thread");
+const ledger_1 = require("./ledger");
+/** Stop do Claude prova fim de turno, não um resultado CHECK autenticado. */
+function requireSessionReviewRuntime(runtime) {
+    if (runtime !== 'codex')
+        throw Error('maestro.authority.runtime-unsupported: independence=sessions exige revisor codex; ' +
+            `runtime ${runtime} ainda não fornece recibo autenticado de conclusão CHECK`);
+}
+const referenceSchema = zod_1.z.object({
+    threadId: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/),
+    sessionId: zod_1.z.string().min(1).max(160).regex(/^[a-zA-Z0-9._-]+$/),
+    worktree: zod_1.z.string().min(1).max(4096).refine(path.isAbsolute),
+}).strict();
+function parseSessionReviewBinding(input) {
+    const result = zod_1.z.object({ conductor: referenceSchema, executor: referenceSchema, reviewer: referenceSchema }).strict().safeParse(input);
+    if (!result.success)
+        throw Error('maestro.authority.binding');
+    return result.data;
+}
+/** Todos os caminhos são derivados da thread; referências recebidas são apenas seletores. */
+function verifySessionReview(root, binding) {
+    if (!binding || !binding.conductor || !binding.executor || !binding.reviewer)
+        throw Error('maestro.authority.unproven');
+    binding = parseSessionReviewBinding(binding);
+    const refs = [binding.conductor, binding.executor, binding.reviewer];
+    if (new Set(refs.map(r => r.sessionId)).size !== 3)
+        throw Error('maestro.authority.self-review');
+    const allowedPhases = [['GOAL', 'PLAN'], ['GO'], ['CHECK']];
+    const records = refs.map((ref, index) => {
+        const thread = (0, thread_1.lerThread)(root, ref.threadId);
+        if (!thread.worktree || !path.isAbsolute(ref.worktree) || thread.worktree !== ref.worktree ||
+            fs.realpathSync(ref.worktree) !== ref.worktree)
+            throw Error('maestro.authority.scope');
+        const matches = thread.sessoes.filter(s => s.sessionId === ref.sessionId);
+        if (matches.length !== 1)
+            throw Error('maestro.authority.unproven');
+        const session = matches[0];
+        if (!session?.verificada || !session.runtime || !allowedPhases[index].includes(session.fase))
+            throw Error('maestro.authority.unproven');
+        const events = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(root, thread.id));
+        const dispatch = events.filter(e => e.tipo === 'phase_dispatch' && e.sessionId === session.sessionId).at(-1);
+        if (!dispatch || !(dispatch.fase === session.fase && dispatch.runtime === session.runtime && dispatch.cwd === ref.worktree &&
+            dispatch.promptSha256 === session.promptSha256 && dispatch.slug === session.slug))
+            throw Error('maestro.authority.unproven');
+        const verified = events.find(e => e.tipo === 'phase_dispatch_verified' && e.sessionId === session.sessionId &&
+            e.slug === session.slug && e.encontrada === true && typeof e.fonte === 'string' && e.fonte.length > 0);
+        if (!session.promptPath)
+            throw Error('maestro.authority.unproven');
+        const prompt = path.resolve(root, session.promptPath);
+        const scope = fs.realpathSync((0, thread_1.dirThread)(root, thread.id)) + path.sep;
+        if (!dispatch?.eventId || !verified?.eventId || !fs.realpathSync(prompt).startsWith(scope) ||
+            (0, node_crypto_1.createHash)('sha256').update(fs.readFileSync(prompt)).digest('hex') !== session.promptSha256)
+            throw Error('maestro.authority.unproven');
+        return { session, dispatch, verified };
+    });
+    if (binding.executor.threadId !== binding.reviewer.threadId ||
+        binding.executor.worktree !== binding.reviewer.worktree)
+        throw Error('maestro.authority.scope');
+    return { ...binding, schema: 'ork.session-review/v1', runtime: records[2].session.runtime,
+        dispatchEvents: records.flatMap(r => [String(r.dispatch.eventId), String(r.verified.eventId)]) };
+}
+/** Despachar CHECK não equivale a concluí-lo. Só o resultado observado pelo núcleo conta. */
+function verifyCompletedSessionReview(root, binding, envelope, verdict = 'approved') {
+    const proof = verifySessionReview(root, binding);
+    const thread = (0, thread_1.lerThread)(root, proof.reviewer.threadId);
+    const session = thread.sessoes.find(s => s.sessionId === proof.reviewer.sessionId);
+    requireSessionReviewRuntime(session.runtime);
+    const events = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(root, thread.id));
+    const executor = thread.sessoes.filter(s => s.fase === 'GO').at(-1);
+    const executionIndex = events.findIndex(e => e.eventId === proof.dispatchEvents[2]);
+    const reviewIndex = events.findIndex(e => e.eventId === proof.dispatchEvents[4]);
+    const executionTime = Date.parse(executor?.despachadaEm ?? '');
+    const reviewTime = Date.parse(session.despachadaEm ?? '');
+    // CHECK antigo não pode validar GO novo, mesmo na mesma thread/worktree.
+    if (executor?.sessionId !== proof.executor.sessionId || executionIndex < 0 || reviewIndex <= executionIndex ||
+        !Number.isFinite(executionTime) || !Number.isFinite(reviewTime) || reviewTime < executionTime ||
+        events.slice(executionIndex + 1).some(e => e.tipo === 'phase_dispatch' && e.fase === 'GO'))
+        throw Error('maestro.authority.review-stale');
+    const approval = envelope ? events.filter(e => e.tipo === 'objective_envelope_approved' && e.objectiveId === envelope.objectiveId).at(-1) : undefined;
+    if (envelope && (!approval?.eventId || approval.envelopeHash !== envelope.hash || approval.version !== envelope.version ||
+        approval.approvedAt !== envelope.approvedAt || events.indexOf(approval) >= executionIndex ||
+        !/^[a-f0-9]{64}$/.test(envelope.hash) || !Number.isSafeInteger(envelope.version) || envelope.version < 1 ||
+        !Number.isFinite(Date.parse(envelope.approvedAt)) || executionTime < Date.parse(envelope.approvedAt) ||
+        Date.parse(events[executionIndex].ts) < Date.parse(envelope.approvedAt)))
+        throw Error('maestro.authority.envelope-stale');
+    const result = events.filter(e => e.tipo === 'phase_result' && e.sessionId === session.sessionId).at(-1);
+    const completed = result?.classificacao === 'fase_concluida' && result.ok === true;
+    // Falha de qualidade pode concluir CHECK com parecer negativo. Transporte interrompido,
+    // espera humana e precondições ausentes não são revisão, mesmo com verdict=rejected.
+    // Política sem retry (ci.failed) preserva o bloqueio, mas não equivale a fase concluída:
+    // todo parecer negativo exige o terminal nativo do controller correlacionado pelo watcher.
+    const rejected = verdict === 'rejected' && result?.classificacao === 'gate_blocked' && result.ok === false &&
+        ['claims.failed', 'claims.unverifiable', 'verify.regression', 'verify.failed', 'ci.failed'].includes(String(result.motivo)) &&
+        result.conclusaoNativa === true && result.conclusaoNativaAusente === null &&
+        result.exitCode === 0 && result.signal === null &&
+        result.exitCodeFonte === 'controller.close' && result.fonteVencedora === 'rollout';
+    if (typeof result?.eventId !== 'string' || !result.eventId || result.fase !== 'CHECK' || result.runtime !== session.runtime ||
+        result.despachoEm !== session.despachadaEm || result.origem !== 'sessions.watch' ||
+        (!completed && !rejected) ||
+        typeof result.sensorResultId !== 'string' || !result.sensorResultId ||
+        typeof session.despachadaEm !== 'string' || !Number.isFinite(Date.parse(session.despachadaEm)) ||
+        !Number.isFinite(Date.parse(result.ts)) || Date.parse(result.ts) < Date.parse(session.despachadaEm))
+        throw Error('maestro.authority.review-incomplete');
+    if (events.indexOf(result) <= reviewIndex)
+        throw Error('maestro.authority.review-stale');
+    return { ...proof, executionEvent: String(events[executionIndex].eventId), reviewResultEvent: result.eventId,
+        ...(envelope ? { envelope: { ...envelope }, envelopeApprovalEvent: String(approval.eventId) } : {}) };
+}

package/dist/maestro-cli.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMaestro = readMaestro;
+exports.maestroText = maestroText;
+exports.runMaestroCli = runMaestroCli;
+const maestro_discovery_1 = require("./maestro-discovery");
+const maestro_contract_1 = require("./maestro-contract");
+const maestro_snapshot_1 = require("./maestro-snapshot");
+const maestro_sources_1 = require("./maestro-sources");
+const maestro_actions_1 = require("./maestro-actions");
+const maestro_runtime_1 = require("./maestro-runtime");
+const horario_1 = require("./horario");
+function readMaestro(context, options) {
+    const observations = options.native && options.threadId ? (0, maestro_runtime_1.nativeForThread)(context.root, options.threadId) : [];
+    return (0, maestro_snapshot_1.maestroSnapshot)(context, { ...options, collect: ctx => {
+            const sources = (0, maestro_sources_1.collectMaestroSources)(ctx, { threadId: options.threadId, native: observations });
+            if (options.host.child && sources.sections.portfolio) {
+                const ids = new Set((sources.sections.demands?.items ?? []).flatMap(d => d.refs.filter(r => r.kind === 'project').map(r => r.id)));
+                const visible = sources.sections.portfolio.items.filter(p => ids.has(p.id));
+                const parents = new Set(visible.flatMap(p => p.refs.map(r => r.id)));
+                sources.sections.portfolio.items = sources.sections.portfolio.items.filter(p => ids.has(p.id) || parents.has(p.id));
+                sources.gaps = sources.gaps.filter(g => !g.startsWith('portfolio.'));
+                sources.conflicts = sources.conflicts.filter(c => !c.startsWith('entity.') || visible.some(p => c.endsWith(':' + p.id)));
+            }
+            sources.sections.nextActions = (0, maestro_actions_1.proposeMaestroActions)(sources.sections.threads?.items ?? [], options.host);
+            if (sources.sections.threads?.state === 'unavailable') {
+                sources.sections.nextActions.state = 'unavailable';
+                sources.sections.nextActions.gaps.push('threads.unavailable');
+            }
+            sources.fingerprint = (0, maestro_sources_1.digest)([sources.fingerprint, sources.sections]);
+            return sources;
+        } });
+}
+function maestroText(snapshot) {
+    return [`${snapshot.project.name} · panorama Maestro`,
+        // I-35: o snapshot guarda ISO; o texto ao dono diz quando consultou, no fuso dele.
+        `• Consulta: ${(0, horario_1.formatarDataHoraRotulada)(snapshot.observedAt, { agora: snapshot.observedAt })}`,
+        ...maestro_contract_1.SECTION_NAMES.map(name => {
+            const s = snapshot.sections[name];
+            return `• ${name}: ${s.state} · ${s.coverage.returned}/${s.coverage.total ?? '?'}${s.coverage.omitted ? ' · mais itens disponíveis' : ''}`;
+        }),
+        ...snapshot.sections.threads.items.slice(0, 8).map(t => `  ${t.title}: ${t.facts.phase} · ${t.status}`),
+        `• Recomendo: ${snapshot.conflicts.length ? 'reler as fontes em conflito' : snapshot.gaps.length ? 'conferir as lacunas antes de agir' : 'escolher uma thread para ver o detalhe'}.`,
+        'Use ork maestro --json para cobertura e ações; --thread ID consulta o detalhe nativo.',
+    ].join('\n');
+}
+function runMaestroCli(argv, cwd = process.cwd(), trusted = {}, io = { out: (v) => console.log(v), err: (v) => console.error(v) }) {
+    if (argv.length === 1 && argv[0] === '--help') {
+        io.out('ork maestro [--json] [--thread ID] [--section NOME --offset N]\nConsulta sem criar ou despachar trabalho. Na conversa, diga: orkastery maestro.');
+        return 0;
+    }
+    try {
+        let json = false, threadId, section, offset;
+        const seen = new Set();
+        for (let i = 0; i < argv.length; i++) {
+            const arg = argv[i];
+            if (seen.has(arg))
+                throw Error('maestro.arguments.invalid');
+            seen.add(arg);
+            if (arg === '--json')
+                json = true;
+            else if (arg === '--thread') {
+                threadId = argv[++i];
+                if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(threadId ?? ''))
+                    throw Error('maestro.arguments.invalid');
+            }
+            else if (arg === '--section') {
+                section = argv[++i];
+                if (!maestro_contract_1.SECTION_NAMES.includes(section))
+                    throw Error('maestro.arguments.invalid');
+            }
+            else if (arg === '--offset') {
+                const raw = argv[++i];
+                if (!/^\d+$/.test(raw ?? ''))
+                    throw Error('maestro.arguments.invalid');
+                offset = Number(raw);
+                if (!Number.isSafeInteger(offset))
+                    throw Error('maestro.arguments.invalid');
+            }
+            else
+                throw Error('maestro.arguments.invalid');
+        }
+        if ((section === undefined) !== (offset === undefined))
+            throw Error('maestro.arguments.invalid');
+        const context = (0, maestro_discovery_1.discoverMaestro)({ cwd, ...trusted });
+        const snapshot = readMaestro(context, { threadId, offsets: section ? { [section]: offset } : undefined, native: true,
+            host: { tools: ['ork_thread_status', 'ork_observe', 'ork_git_status'], child: false } });
+        io.out(json ? JSON.stringify(snapshot) : maestroText(snapshot));
+        return 0;
+    }
+    catch (e) {
+        const message = e.message;
+        const code = /^maestro\.[a-z_.]+$/.test(message) ? message : 'maestro.source.unavailable';
+        io.err(JSON.stringify({ error: code }));
+        return code === 'maestro.arguments.invalid' ? 2 : 1;
+    }
+}

package/dist/maestro-contract.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maestroSnapshotSchema = exports.maestroSectionSchema = exports.maestroItemSchema = exports.maestroActionSchema = exports.MAESTRO_ERRORS = exports.SECTION_NAMES = exports.MAESTRO_LIMITS = exports.MAESTRO_SCHEMA = void 0;
+exports.validateMaestroSnapshot = validateMaestroSnapshot;
+/** Projeção pública, sem autoridade para executar operações. */
+const zod_1 = require("zod");
+exports.MAESTRO_SCHEMA = 'ork.maestro-snapshot/v1';
+exports.MAESTRO_LIMITS = { items: 50, bytes: 65536, sourceMs: 2000, totalMs: 10000 };
+exports.SECTION_NAMES = ['portfolio', 'demands', 'threads', 'sessions', 'blockers', 'leases', 'retries', 'hitl', 'ship', 'master', 'nextActions'];
+exports.MAESTRO_ERRORS = ['maestro.project.missing', 'maestro.project.ambiguous', 'maestro.project.scope', 'maestro.source.unavailable', 'maestro.snapshot.stale'];
+const text = zod_1.z.string().max(512);
+const identity = zod_1.z.string().min(1).max(160);
+const fingerprint = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+exports.maestroActionSchema = zod_1.z.object({
+    operation: zod_1.z.enum(['thread.status', 'thread.observe', 'hitl.decide', 'git.status', 'git.commit', 'verify', 'ship', 'retry', 'master', 'phase', 'creation']),
+    available: zod_1.z.boolean(), reason: text, preconditions: zod_1.z.array(text).max(10), readback: text,
+}).strict();
+exports.maestroItemSchema = zod_1.z.object({
+    id: identity, title: text, status: text,
+    refs: zod_1.z.array(zod_1.z.object({ kind: identity, id: identity }).strict()).max(16),
+    facts: zod_1.z.record(zod_1.z.union([text, zod_1.z.number().finite(), zod_1.z.boolean(), zod_1.z.null()])),
+    action: exports.maestroActionSchema.optional(),
+}).strict();
+exports.maestroSectionSchema = zod_1.z.object({
+    state: zod_1.z.enum(['available', 'empty', 'unavailable', 'stale', 'conflict']),
+    source: identity, observedAt: zod_1.z.string().datetime(), fingerprint: fingerprint.nullable(),
+    coverage: zod_1.z.object({ total: zod_1.z.number().int().nonnegative().nullable(), offset: zod_1.z.number().int().nonnegative(),
+        returned: zod_1.z.number().int().min(0).max(50), omitted: zod_1.z.number().int().nonnegative().nullable(),
+        nextOffset: zod_1.z.number().int().nonnegative().nullable(), limit: zod_1.z.literal(50) }).strict(),
+    items: zod_1.z.array(exports.maestroItemSchema).max(50), gaps: zod_1.z.array(text).max(50),
+}).strict();
+exports.maestroSnapshotSchema = zod_1.z.object({
+    schema: zod_1.z.literal(exports.MAESTRO_SCHEMA), observedAt: zod_1.z.string().datetime(), fingerprint,
+    project: zod_1.z.object({ id: identity, name: text, origin: zod_1.z.enum(['installation', 'cwd', 'worktree', 'selection']), fingerprint }).strict(),
+    limits: zod_1.z.object({ items: zod_1.z.literal(50), bytes: zod_1.z.literal(65536), sourceMs: zod_1.z.literal(2000), totalMs: zod_1.z.literal(10000) }).strict(),
+    sections: zod_1.z.object(Object.fromEntries(exports.SECTION_NAMES.map(name => [name, exports.maestroSectionSchema]))).strict(),
+    gaps: zod_1.z.array(text).max(100), conflicts: zod_1.z.array(text).max(100),
+}).strict();
+function validateMaestroSnapshot(input) {
+    const value = exports.maestroSnapshotSchema.parse(input);
+    if (Buffer.byteLength(JSON.stringify(value)) > exports.MAESTRO_LIMITS.bytes)
+        throw Error('maestro.snapshot.size');
+    for (const name of exports.SECTION_NAMES) {
+        const s = value.sections[name], c = s.coverage;
+        if (c.returned !== s.items.length || (c.total !== null && (c.offset + c.returned + (c.omitted ?? 0) !== c.total)) ||
+            (s.state === 'empty' && (c.total !== 0 || s.items.length)) ||
+            // Fonte parcial pode paginar itens observados sem inventar total/omissões.
+            (c.nextOffset !== null && (c.nextOffset !== c.offset + c.returned || c.returned === 0 ||
+                (c.omitted === null ? c.total !== null : c.omitted === 0))))
+            throw Error('maestro.coverage.invalid');
+        if (name === 'nextActions' && s.items.some(item => !item.action))
+            throw Error('maestro.action.invalid');
+    }
+    return value;
+}

package/dist/maestro-discovery.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverMaestro = discoverMaestro;
+exports.revalidateMaestroContext = revalidateMaestroContext;
+/** Descoberta somente entre raízes permitidas. Nenhuma mutação ou busca na home. */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const manifest_1 = require("./manifest");
+const estado_thread_1 = require("./estado-thread");
+const thread_1 = require("./thread");
+const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+function physical(file) {
+    const absolute = path.resolve(file);
+    if (fs.realpathSync(absolute) !== absolute)
+        throw Error('maestro.project.scope');
+    return absolute;
+}
+function context(root, origin) {
+    const real = physical(root);
+    const manifest = ['orkastery.yaml', 'devmaster.yaml'].map(f => path.join(real, f)).find(f => fs.existsSync(f));
+    if (!manifest)
+        throw Error('maestro.project.missing');
+    physical(manifest);
+    const stat = fs.statSync(manifest);
+    if (!stat.isFile() || stat.size > 16384)
+        throw Error('maestro.project.scope');
+    for (const name of ['.orkastery', '.orkastery/threads', '.orkastery/objectives']) {
+        const file = path.join(real, name);
+        if (fs.existsSync(file) && !inside(real, fs.realpathSync(file)))
+            throw Error('maestro.project.scope');
+    }
+    const loaded = (0, manifest_1.carregarManifesto)(real);
+    if (!loaded || loaded.raiz !== real || loaded.erros.length)
+        throw Error('maestro.project.scope');
+    const fingerprint = (0, node_crypto_1.createHash)('sha256').update(real).update(fs.readFileSync(manifest))
+        .update(`${fs.statSync(real).dev}:${fs.statSync(real).ino}:${stat.ino}`).digest('hex');
+    return { root: real, manifest, fingerprint, project: { id: loaded.manifesto.project.abbrev,
+            name: loaded.manifesto.project.name, origin, fingerprint } };
+}
+function localRoot(cwd) {
+    let current = cwd;
+    for (;;) {
+        if (['orkastery.yaml', 'devmaster.yaml'].some(f => fs.existsSync(path.join(current, f))))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function discoverMaestro(options) {
+    const cwd = physical(options.cwd), nearest = localRoot(cwd);
+    const candidates = [...new Set(options.pinned ? [options.pinned] : options.allowedRoots ?? (nearest ? [nearest] : []))].map(physical);
+    if (!candidates.length)
+        throw Error('maestro.project.missing');
+    if (options.selected && !candidates.includes(path.resolve(options.selected)))
+        throw Error('maestro.project.scope');
+    const chosen = options.selected ? path.resolve(options.selected) : candidates.length === 1 ? candidates[0] : undefined;
+    if (!chosen)
+        throw Error('maestro.project.ambiguous');
+    const origin = options.selected ? 'selection' : options.pinned ? 'installation' : 'cwd';
+    // Pin/seleção limitam candidatos; não dispensam o vínculo com o estado canônico.
+    const canonical = (0, estado_thread_1.raizDoEstado)(chosen);
+    if (canonical !== chosen) {
+        const git = path.join(chosen, '.git');
+        physical(git);
+        const match = /^gitdir: (.+)\s*$/.exec(fs.readFileSync(git, 'utf8'));
+        if (!match)
+            throw Error('maestro.project.scope');
+        const gitdir = physical(path.resolve(chosen, match[1].trim()));
+        const common = physical(path.join(canonical, '.git'));
+        const worktrees = physical(path.join(common, 'worktrees'));
+        if (path.dirname(gitdir) !== worktrees ||
+            path.resolve(gitdir, fs.readFileSync(physical(path.join(gitdir, 'commondir')), 'utf8').trim()) !== common ||
+            path.resolve(gitdir, fs.readFileSync(physical(path.join(gitdir, 'gitdir')), 'utf8').trim()) !== git)
+            throw Error('maestro.project.scope');
+        const localState = physical(path.join(chosen, '.orkastery/threads'));
+        const bindings = (0, thread_1.listarIds)(canonical).filter(id => (0, thread_1.lerThread)(canonical, id).worktree === chosen);
+        if (bindings.length !== 1)
+            throw Error('maestro.project.scope');
+        const bound = path.join(localState, bindings[0]);
+        if (!fs.existsSync(bound) || fs.realpathSync(bound) !== path.join(canonical, '.orkastery/threads', bindings[0]))
+            throw Error('maestro.project.scope');
+        if (fs.existsSync(localState))
+            for (const name of fs.readdirSync(localState)) {
+                const file = path.join(localState, name), target = path.join(canonical, '.orkastery/threads', name);
+                if (fs.lstatSync(file).isSymbolicLink() && fs.realpathSync(file) !== target)
+                    throw Error('maestro.project.scope');
+            }
+        return context(canonical, 'worktree');
+    }
+    return context(chosen, origin);
+}
+function revalidateMaestroContext(value) {
+    const current = context(value.root, value.project.origin);
+    if (current.fingerprint !== value.fingerprint || current.manifest !== value.manifest)
+        throw Error('maestro.snapshot.stale');
+}