@orkastery/cli 0.5.0 → 0.5.3

package/dist/ship.js

@@ -50,6 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitQueIncorporou = commitQueIncorporou;
 exports.autorizacaoDePush = autorizacaoDePush;
 exports.arvoreComBranch = arvoreComBranch;
 exports.prepararArvore = prepararArvore;
@@ -62,6 +63,7 @@ exports.ship = ship;
 exports.textoDoShip = textoDoShip;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const gates_1 = require("./gates");
 const leases_1 = require("./leases");
 const ledger_1 = require("./ledger");
@@ -76,6 +78,45 @@ const contrato_publico_1 = require("./contrato-publico");
 const prova_minima_1 = require("./prova-minima");
 const horario_1 = require("./horario");
 const fabrica_publicar_1 = require("./fabrica-publicar");
+const branch_de_estado_1 = require("./branch-de-estado");
+/**
+ * RM-037 (fatia 5, A1): o commit de primeiro pai da base que incorporou o `shaDe`: o merge que trouxe a branch, ou
+ * o proprio `shaDe` quando a base avancou por fast-forward ate ele. Com a branch ja incorporada, a ponta da base e
+ * outra coisa: no `ship_done` da ork-docsusuarios (27/09/2026), o unico do `ork ship` com `jaIncorporado` nos ledgers
+ * deste projeto, ela era o merge de outra thread. O que trouxe a branch e o commit mais velho do primeiro pai da base
+ * que descende do `shaDe`. GO-FIX (rodada 1 do CHECK): `--first-parent` junto com `--ancestry-path` so propaga a
+ * descendencia pelos commits de primeiro pai, e o merge do PR que recebeu "Update branch" no GitHub (o pai dele e um
+ * merge que descende do `shaDe`, nao o `shaDe`) sumia da lista; agora sao duas listas e a intersecao. `null` quando o
+ * git nao responde.
+ */
+function commitQueIncorporou(raiz, shaDe, ponta, passos = []) {
+    if (shaDe === ponta)
+        return shaDe;
+    // `passos` recebe os comandos que de fato rodaram, na ordem: e a evidencia do ship (sugestao da conferencia da rodada 2).
+    const curto = (sha) => sha.slice(0, 8);
+    // As listas crescem com o historico entre a branch e a ponta: o buffer vai alem do 1 MiB padrao do spawnSync.
+    const listar = (args) => {
+        passos.push(`git ${args.map((a) => a.replace(/^([0-9a-f]{40,64})\.\.([0-9a-f]{40,64})$/, (_, x, y) => `${curto(x)}..${curto(y)}`)).join(' ')}`);
+        const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: raiz, encoding: 'utf8', timeout: 120000, maxBuffer: 256 * 1024 * 1024 });
+        return r.status === 0 && !r.error ? r.stdout.split('\n').filter((l) => /^[0-9a-f]{40,64}$/.test(l)) : null;
+    };
+    const primeiroPai = listar(['rev-list', '--first-parent', `${shaDe}..${ponta}`]);
+    const descendentes = listar(['rev-list', '--ancestry-path', `${shaDe}..${ponta}`]);
+    if (!primeiroPai || !descendentes)
+        return null;
+    const doShaDe = new Set(descendentes);
+    // Do mais velho para o mais novo: o primeiro de primeiro pai que descende do `shaDe`.
+    const maisVelho = [...primeiroPai].reverse().find((c) => doShaDe.has(c));
+    if (!maisVelho)
+        return null;
+    // O primeiro pai dele e o proprio `shaDe`: a branch ja estava no primeiro pai da base (fast-forward). Sem a resposta
+    // do git, nada e gravado: devolver o mais velho poria no `mergeSha` o filho do `shaDe` (sugestao da rodada 2).
+    passos.push(`git rev-parse ${curto(maisVelho)}^1`);
+    const pai = (0, util_1.exec)('git', ['rev-parse', `${maisVelho}^1`], raiz);
+    if (!pai.ok)
+        return null;
+    return pai.stdout.trim() === shaDe ? shaDe : maisVelho;
+}
 /** Os caminhos de contrato publico que a entrega traz sobre a base (diff desde o merge-base). */
 function contratosDaEntrega(raiz, shaPara, shaDe) {
     const base = (0, util_1.exec)('git', ['merge-base', shaPara, shaDe], raiz);
@@ -185,7 +226,7 @@ function prepararArvore(raiz, para) {
     }
     const dir = dirTemporarioDeShip(raiz, para);
     fs.mkdirSync(path.dirname(dir), { recursive: true });
-    const r = (0, util_1.exec)('git', ['worktree', 'add', dir, para], raiz);
+    const r = (0, util_1.exec)('git', ['worktree', 'add', '--', dir, para], raiz);
     if (!r.ok) {
         throw new Error(`nao foi possivel montar a arvore de merge de "${para}": ${(r.stderr || r.stdout).trim()}`);
     }
@@ -211,7 +252,8 @@ function shaDaRef(dir, ref) {
  * codigo de saida do `git push` nao prova que o remoto ficou com o commit certo.
  */
 function shaNoRemoto(dir, remoto, branch) {
-    const r = (0, util_1.exec)('git', ['ls-remote', remoto, `refs/heads/${branch}`], dir, 120000);
+    // RM-047: so nome de remoto chega ao git, e depois do `--` (nunca vira opcao nem transporte).
+    const r = (0, util_1.exec)('git', ['ls-remote', '--', (0, branch_de_estado_1.exigirRemoto)(remoto, 'ship'), `refs/heads/${branch}`], dir, 120000);
     if (!r.ok)
         return null;
     const linha = r.stdout.split('\n').find((l) => l.trim() !== '');
@@ -222,7 +264,7 @@ function shaNoRemoto(dir, remoto, branch) {
 }
 /** O remoto esta configurado neste repositorio? */
 function remotoConfigurado(dir, remoto) {
-    return (0, util_1.exec)('git', ['remote', 'get-url', remoto], dir).ok;
+    return (0, util_1.exec)('git', ['remote', 'get-url', '--', (0, branch_de_estado_1.exigirRemoto)(remoto, 'ship')], dir).ok;
 }
 function baseDoResultado(thread, de, opcoes) {
     return {
@@ -237,6 +279,7 @@ function baseDoResultado(thread, de, opcoes) {
         shaDe: '',
         shaParaAntes: '',
         mergeSha: null,
+        pontaDaBase: null,
         jaIncorporado: false,
         remoto: opcoes.remoto ?? 'origin',
         shaRemoto: null,
@@ -329,7 +372,10 @@ function ship(carregado, threadId, opcoes) {
     const dir = (0, thread_1.dirThread)(raiz, threadId);
     const de = opcoes.de ?? thread.base.branch;
     const para = opcoes.para;
-    const remoto = opcoes.remoto ?? 'origin';
+    // RM-047: o `--remoto` vem da linha de comando. Antes de qualquer git (inclusive a leitura da reversao),
+    // so nome de remoto passa; o resto recusa com `ship.remoto-invalido`, e o ship nao entrega sem push provado
+    // por um remoto que nunca existiu.
+    const remoto = (0, branch_de_estado_1.exigirRemoto)(opcoes.remoto ?? 'origin', 'ship');
     const r = baseDoResultado(thread, de, opcoes);
     // I-43 (T7): antes de qualquer coisa, se a entrega ANTERIOR desta thread foi
     // revertida na base, isso vira `rollback_done`. E o insumo de maior peso do indice
@@ -348,6 +394,8 @@ function ship(carregado, threadId, opcoes) {
             correcao,
             de,
             para,
+            // Fatia 2 do ensaio da 0.5.0 (P2): o gate do ensaio e marcado, e os leitores de estado o ignoram.
+            ...(r.dryRun ? { dryRun: true } : {}),
         });
         (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipBloqueado, {
             de,
@@ -373,6 +421,26 @@ function ship(carregado, threadId, opcoes) {
     const branchAtrasDaBase = pontaDe && pontaPara && de !== para
         ? !(0, util_1.exec)('git', ['merge-base', '--is-ancestor', pontaPara, pontaDe], raiz).ok
         : undefined;
+    // Fatia 2 do ensaio da 0.5.0 (P9): sem delta (a branch da thread ja esta contida na base) e com a base
+    // local a frente da ref de rastreio do remoto, o push publicaria a base sem merge de thread. A medida e
+    // local, sem rede; sem remoto, sem ref de rastreio ou com --sem-push, o fato nao vem e nada muda.
+    // CHECK, rodada 1 (B1): o merge que o proprio ship ja fez e nao chegou ao remoto (push recusado,
+    // --sem-push, retomada do MCP) tambem deixa a base a frente sem delta, mas leva a ponta da thread como
+    // pai que nao e o primeiro: e entrega de thread, e o retry empurra como antes. Rodada 2 (S-R2-1): so
+    // quando a linha principal da base, alem do remoto, e toda de merge; commit direto nela segue barrado.
+    const rastreio = pontaDe && pontaPara && de !== para && !opcoes.semPush && remotoConfigurado(raiz, remoto)
+        ? shaDaRef(raiz, `refs/remotes/${remoto}/${para}`) : null;
+    const mergeDaThreadNaBase = (desde) => {
+        const diretos = (0, util_1.exec)('git', ['rev-list', '--first-parent', '--no-merges', `${desde}..${pontaPara}`], raiz);
+        return diretos.ok && diretos.stdout.trim() === '' &&
+            (0, util_1.exec)('git', ['rev-list', '--merges', '--parents', `${desde}..${pontaPara}`], raiz).stdout.split('\n')
+                .some((linha) => linha.trim().split(' ').slice(2).includes(pontaDe));
+    };
+    const semDeltaComBaseAFrente = rastreio
+        ? (0, util_1.exec)('git', ['merge-base', '--is-ancestor', pontaDe, pontaPara], raiz).ok &&
+            !(0, util_1.exec)('git', ['merge-base', '--is-ancestor', pontaPara, rastreio], raiz).ok &&
+            !mergeDaThreadNaBase(rastreio)
+        : undefined;
     const violacoes = (0, policies_1.avaliarPolicies)(manifesto, {
         gate: 'ship',
         de,
@@ -380,6 +448,8 @@ function ship(carregado, threadId, opcoes) {
         baseBranch: manifesto.worktree.base_branch,
         threadId,
         branchAtrasDaBase,
+        semDeltaComBaseAFrente,
+        remoto,
     });
     r.violacoes = violacoes;
     if (!r.dryRun) {
@@ -425,7 +495,7 @@ function ship(carregado, threadId, opcoes) {
     }
     // 4. Lease `main-tree`: so uma thread mergeia por vez.
     if (r.dryRun) {
-        const ocupado = (0, leases_1.lerLease)(raiz, leases_1.LEASE_MAIN_TREE);
+        const ocupado = (0, leases_1.leasesColidentes)(raiz, leases_1.LEASE_MAIN_TREE)[0] ?? null;
         r.leaseOcupadoPor = ocupado;
         // O ensaio tambem responde ONDE o merge aconteceria e se aquela arvore esta limpa:
         // descobrir isso so na hora do merge real seria descobrir tarde demais.
@@ -434,11 +504,17 @@ function ship(carregado, threadId, opcoes) {
             ? `${dona} (arvore que tem ${para} em check-out; ${temAlteracaoNaoCommitada(dona) ? 'SUJA, o ship reprovaria com tree.blocked' : 'limpa'})`
             : `worktree temporaria em ${path.join((0, manifest_1.dirEstado)(raiz), 'tmp')} (ninguem tem ${para} em check-out)`;
         r.detalhe = `arvore de merge: ${arvoreDoMerge}`;
+        // Ensaio de 03/10 (R5): sem remoto (ou com --sem-push), o ensaio diz o mesmo que o ship real, e nao
+        // promete um push e uma prova que nao vao acontecer.
+        const semPushNoReal = opcoes.semPush ? 'push nao executado por --sem-push (merge local concluido)'
+            : !remotoConfigurado(raiz, remoto) ? `remoto "${remoto}" nao configurado: merge local concluido, sem push a provar` : null;
         r.passos = [
             `arvore de merge: ${arvoreDoMerge}`,
             `git merge --no-ff ${de} -m "<mensagem de ship>"`,
-            `git push ${remoto} ${para}`,
-            `git ls-remote ${remoto} refs/heads/${para}   (prova do push)`,
+            ...(semPushNoReal ? [`sem push: ${semPushNoReal}`] : [
+                `git push ${remoto} ${para}`,
+                `git ls-remote ${remoto} refs/heads/${para}   (prova do push)`,
+            ]),
         ];
         (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipIniciado, {
             de,
@@ -469,11 +545,11 @@ function ship(carregado, threadId, opcoes) {
             posicao: aquisicao.posicaoNaFila,
             naFrente: (0, leases_1.esperandoPor)(raiz, leases_1.LEASE_MAIN_TREE).length,
             bloqueadaPor: dono?.thread ?? '(desconhecida)',
-            motivo: 'lease.busy',
+            motivo: aquisicao.motivo ?? 'lease.busy',
         });
-        return bloquear('lease.busy', `lease ${leases_1.LEASE_MAIN_TREE} esta com a thread ${dono?.thread ?? '(desconhecida)'} ` +
+        return bloquear(aquisicao.motivo ?? 'lease.busy', aquisicao.falhaRetomada ? aquisicao.detalhe : `lease ${leases_1.LEASE_MAIN_TREE} esta com a thread ${dono?.thread ?? '(desconhecida)'} ` +
             `desde ${dono?.adquiridoEm ?? '?'} (${dono?.motivo ?? 'sem motivo'}); ` +
-            `esta thread entrou na merge queue na posicao ${aquisicao.posicaoNaFila}`, `espere a vez na fila (ork lease list), ou libere com: ork lease release ${leases_1.LEASE_MAIN_TREE} --forcar`);
+            `esta thread entrou na merge queue na posicao ${aquisicao.posicaoNaFila}`, aquisicao.correcao);
     }
     r.lease = aquisicao.lease;
     (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.leaseAdquirido, {
@@ -508,6 +584,9 @@ function ship(carregado, threadId, opcoes) {
         const jaIncorporado = (0, util_1.exec)('git', ['merge-base', '--is-ancestor', shaDe, shaPara], raiz).ok;
         r.jaIncorporado = jaIncorporado;
         let mergeSha = shaPara;
+        // RM-037 (fatia 5, A1): a ponta que o push prova. Com o merge feito aqui, e ele; com a branch ja incorporada, a
+        // ponta de antes, que pode trazer outros merges depois do que entregou esta thread.
+        let pontaDaBase = shaPara;
         if (!jaIncorporado) {
             const mensagem = opcoes.mensagem ??
                 `ship(${threadId}): merge de ${de} em ${para}\n\n` +
@@ -515,7 +594,8 @@ function ship(carregado, threadId, opcoes) {
                     `modo: ${(0, modos_1.tagDoModo)(thread.modo)}\n` +
                     `autorizado por: ${autorizacao.por} (${autorizacao.tipo})\n` +
                     `verificado em: HEAD ${verificacao.commit}\n`;
-            const merge = (0, util_1.exec)('git', ['merge', '--no-ff', de, '-m', mensagem], arvore.dir, 300000);
+            // RM-047: o merge e do sha verificado, e nao do nome que veio de `--de` (nome nunca vira opcao do git).
+            const merge = (0, util_1.exec)('git', ['merge', '--no-ff', '-m', mensagem, shaDe], arvore.dir, 300000);
             passos.push(`git merge --no-ff ${de}`);
             if (!merge.ok) {
                 (0, util_1.exec)('git', ['merge', '--abort'], arvore.dir);
@@ -527,6 +607,7 @@ function ship(carregado, threadId, opcoes) {
                 return bloquear('artifact.missing', 'nao foi possivel ler o HEAD apos o merge', 'confira o repositorio');
             }
             mergeSha = novo;
+            pontaDaBase = novo;
             // Verificacao independente do merge: a origem precisa ser ancestral do resultado.
             const incorporou = (0, util_1.exec)('git', ['merge-base', '--is-ancestor', shaDe, mergeSha], arvore.dir).ok;
             passos.push(`git merge-base --is-ancestor ${shaDe.slice(0, 8)} ${mergeSha.slice(0, 8)}`);
@@ -535,9 +616,16 @@ function ship(carregado, threadId, opcoes) {
             }
         }
         else {
-            passos.push(`(nada a mergear: ${de} ja e ancestral de ${para})`);
+            // RM-037 (fatia 5, A1): o merge que trouxe a branch, e nao a ponta da base.
+            const incorporadoEm = commitQueIncorporou(raiz, shaDe, shaPara, passos);
+            if (!incorporadoEm) {
+                return bloquear('artifact.missing', `${de} ja e ancestral de ${para}, mas o git nao achou o commit de primeiro pai que o incorporou`, 'confira o repositorio: o ship_done precisa do merge que entregou a thread');
+            }
+            mergeSha = incorporadoEm;
+            passos.push(`(nada a mergear: ${de} ja e ancestral de ${para}, incorporado em ${mergeSha.slice(0, 8)})`);
         }
         r.mergeSha = mergeSha;
+        r.pontaDaBase = pontaDaBase;
         opcoes.revalidarGit?.('push', arvore.dir);
         // 6. Push PROVADO por ls-remote.
         const temRemoto = remotoConfigurado(arvore.dir, remoto);
@@ -551,8 +639,8 @@ function ship(carregado, threadId, opcoes) {
         else {
             const existeNoRemoto = shaNoRemoto(arvore.dir, remoto, para) !== null;
             const argsPush = existeNoRemoto
-                ? ['push', remoto, `${para}:refs/heads/${para}`]
-                : ['push', '-u', remoto, `${para}:refs/heads/${para}`];
+                ? ['push', '--', remoto, `refs/heads/${para}:refs/heads/${para}`]
+                : ['push', '-u', '--', remoto, `refs/heads/${para}:refs/heads/${para}`];
             const push = (0, util_1.exec)('git', argsPush, arvore.dir, 300000);
             passos.push(`git ${argsPush.join(' ')}`);
             if (!push.ok) {
@@ -563,10 +651,10 @@ function ship(carregado, threadId, opcoes) {
             const shaRemoto = shaNoRemoto(arvore.dir, remoto, para);
             passos.push(`git ls-remote ${remoto} refs/heads/${para}`);
             r.shaRemoto = shaRemoto;
-            r.pushVerificado = shaRemoto !== null && shaRemoto === mergeSha;
+            r.pushVerificado = shaRemoto !== null && shaRemoto === pontaDaBase;
             if (!r.pushVerificado) {
                 r.passos = passos;
-                return bloquear('runtime.unavailable', `ls-remote devolveu ${shaRemoto ?? '(nada)'} e o destino local esta em ${mergeSha}: ` +
+                return bloquear('runtime.unavailable', `ls-remote devolveu ${shaRemoto ?? '(nada)'} e o destino local esta em ${pontaDaBase}: ` +
                     'o push nao ficou provado', 'rode o ship de novo e confira o remoto');
             }
         }
@@ -585,6 +673,8 @@ function ship(carregado, threadId, opcoes) {
             shaDe,
             shaParaAntes: shaPara,
             mergeSha,
+            // RM-037 (fatia 5, A1): a ponta da base vai em campo proprio; o `mergeSha` e o merge que entregou a thread.
+            pontaDaBase,
             jaIncorporado,
             remoto: r.remoto,
             shaRemoto: r.shaRemoto,
@@ -647,12 +737,12 @@ function textoDoShip(r) {
     linhas.push(`                ${local(r.autorizacao.razao)}`);
     if (r.verificacao) {
         const v = r.verificacao;
-        linhas.push(`  verificacao   ${v.ok ? 'passou' : 'REPROVOU'} no HEAD ${v.commit.slice(0, 8)} ` +
+        linhas.push(`  verificacao   ${v.ok ? 'passou' : 'REPROVOU'} no HEAD ${(0, util_1.shaCurto)(v.commit)} ` +
             `(${v.claims.filter((c) => c.verificado).length}/${v.claims.length} claims, ` +
             `${v.comandos.filter((c) => c.ok).length}/${v.comandos.length} comandos)`);
     }
     if (r.ci) {
-        linhas.push(`  ci             ${r.ci.required ? `${r.ci.state.toUpperCase()} ${r.ci.context} em ${r.ci.sha.slice(0, 8)}` : 'não exigido'}`);
+        linhas.push(`  ci            ${r.ci.required ? `${r.ci.state.toUpperCase()} ${r.ci.context} em ${r.ci.sha.slice(0, 8)}` : 'não exigido'}`);
     }
     linhas.push(...(0, policies_1.linhasDeAviso)(r.violacoes ?? []));
     if (r.leaseOcupadoPor) {
@@ -681,11 +771,11 @@ function textoDoShip(r) {
     }
     linhas.push('');
     linhas.push(r.jaIncorporado
-        ? `Nada a mergear: ${r.de} ja estava em ${r.para}.`
+        ? `Nada a mergear: ${r.de} ja estava em ${r.para}, incorporado em ${r.mergeSha}.`
         : `Merge --no-ff concluido: ${r.mergeSha}`);
     if (r.pushVerificado) {
         linhas.push(`Push PROVADO: ls-remote de ${r.remoto}/${r.para} devolveu ${r.shaRemoto}`);
-        linhas.push(`  e o destino local esta no mesmo sha: ${r.mergeSha}`);
+        linhas.push(`  e o destino local esta no mesmo sha: ${r.pontaDaBase ?? r.mergeSha}`);
     }
     else {
         linhas.push(`Push nao provado: ${local(r.detalhe) || 'sem remoto configurado'}`);

package/dist/thread.js

@@ -45,8 +45,18 @@ exports.caminhoThread = caminhoThread;
 exports.listarIds = listarIds;
 exports.lerThread = lerThread;
 exports.gravarThread = gravarThread;
+exports.avisoDeThreadSemBase = avisoDeThreadSemBase;
 exports.idDisponivel = idDisponivel;
+exports.pastaDaWorktree = pastaDaWorktree;
+exports.alvoDaWorktree = alvoDaWorktree;
+exports.worktreePrevista = worktreePrevista;
 exports.criarWorktree = criarWorktree;
+exports.pedidoDeWorktree = pedidoDeWorktree;
+exports.linhaDaWorktree = linhaDaWorktree;
+exports.avisoDeThreadSemWorktree = avisoDeThreadSemWorktree;
+exports.avisoDeWorktreeQueFalharia = avisoDeWorktreeQueFalharia;
+exports.avisoDeChaveSemCommit = avisoDeChaveSemCommit;
+exports.avisoDaWorktree = avisoDaWorktree;
 exports.novaThread = novaThread;
 exports.exigirVarianteCompativel = exigirVarianteCompativel;
 exports.blocoDaThread = blocoDaThread;
@@ -113,9 +123,22 @@ function carimbarBase(raiz) {
     const commit = (0, util_1.exec)('git', ['rev-parse', 'HEAD'], raiz);
     return {
         branch: branch.ok ? branch.stdout.trim() : 'desconhecida',
-        commit: commit.ok ? commit.stdout.trim() : 'desconhecido',
+        commit: commit.ok ? commit.stdout.trim() : util_1.COMMIT_DESCONHECIDO,
     };
 }
+/**
+ * Ensaio da 0.5.0: a thread aberta antes do primeiro commit nascia sem base, e nada avisava; o
+ * ship depois nao tem de onde partir. O aviso vai ao stderr e nao muda a saida do comando.
+ */
+function avisoDeThreadSemBase(thread, gravada) {
+    if (thread.base.commit !== util_1.COMMIT_DESCONHECIDO)
+        return null;
+    return gravada
+        ? `Aviso: o repositório ainda não tem commit, e a thread ${thread.id} nasceu sem base: o ship não tem de onde partir. ` +
+            `Faça o primeiro commit, feche esta com ork thread close ${thread.id} --motivo engano --por <quem> ` +
+            '--justificativa "aberta antes do primeiro commit" e abra outra.'
+        : 'Aviso: o repositório ainda não tem commit, e a thread nasceria sem base: faça o primeiro commit antes de abrir a primeira thread.';
+}
 /** Resolve um id livre a partir do assunto normalizado (`<abbrev>-<assunto>`). */
 function idDisponivel(raiz, abbrev, assunto) {
     let candidato = assunto;
@@ -127,6 +150,43 @@ function idDisponivel(raiz, abbrev, assunto) {
     }
     return { id: `${abbrev}-${candidato}`, assunto: candidato };
 }
+/**
+ * Pasta da worktree de uma thread: `worktree.dir` resolvido na arvore principal, nunca na worktree de onde o comando
+ * roda. P4 do ensaio da 0.5.0 (CHECK): com a chave valendo, o `ork thread new` rodado de dentro da worktree de outra
+ * thread aninhava a nova na pasta da mae, e o release da mae levava a da filha junto.
+ */
+function pastaDaWorktree(carregado, id) {
+    return path.resolve((0, estado_thread_1.raizDoEstado)(carregado.raiz), carregado.manifesto.worktree.dir, id);
+}
+/** Pasta e branch da worktree de uma thread: o que `criarWorktree` cria e o `--dry-run` preve. */
+function alvoDaWorktree(carregado, id, slug, opcoes = {}) {
+    return { dir: pastaDaWorktree(carregado, id), branch: opcoes.branchExistente ?? `ork/${slug}` };
+}
+/**
+ * P4 do ensaio da 0.5.0: a worktree que `criarWorktree` criaria para este id, sem criar nada. Mesma pasta, mesma
+ * branch e o commit de onde ela partiria: a branch existente (ciclo `merge-branch`), senao a base do manifesto,
+ * senao o HEAD. Diz tambem o que faria a criacao recusar: a pasta que ja existe, o repositorio sem commit ou a
+ * branch nova que ja existe.
+ */
+function worktreePrevista(carregado, id, slug, opcoes = {}) {
+    const alvo = alvoDaWorktree(carregado, id, slug, opcoes);
+    const refs = opcoes.branchExistente
+        ? [opcoes.branchExistente]
+        : [opcoes.base ?? carregado.manifesto.worktree.base_branch, 'HEAD'];
+    let commit = null;
+    for (const ref of refs) {
+        const r = (0, util_1.exec)('git', ['rev-parse', '--verify', ref], carregado.raiz);
+        if (r.ok) {
+            commit = r.stdout.trim();
+            break;
+        }
+    }
+    const branchJaExiste = !opcoes.branchExistente &&
+        (0, util_1.exec)('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${alvo.branch}`], carregado.raiz).ok;
+    const falha = fs.existsSync(alvo.dir) ? 'pasta-existe'
+        : commit === null ? 'sem-commit' : branchJaExiste ? 'branch-existe' : null;
+    return { ...alvo, commit, falha };
+}
 /**
  * Cria a worktree isolada da thread (paralelismo sem colisao entre threads).
  *
@@ -136,14 +196,16 @@ function idDisponivel(raiz, abbrev, assunto) {
  */
 function criarWorktree(carregado, id, slug, opcoes = {}) {
     const { raiz, manifesto } = carregado;
-    const dir = path.resolve(raiz, manifesto.worktree.dir, id);
-    const branch = opcoes.branchExistente ?? `ork/${slug}`;
+    const { dir, branch } = alvoDaWorktree(carregado, id, slug, opcoes);
     if (fs.existsSync(dir)) {
         throw new Error(`worktree ja existe em ${dir}`);
     }
     const base = opcoes.base ?? manifesto.worktree.base_branch;
     const commitBase = (0, util_1.exec)('git', ['rev-parse', '--verify', base], raiz);
     const ref = commitBase.ok ? commitBase.stdout.trim() : 'HEAD';
+    // Fatia 2 do ensaio da 0.5.0 (P3): a pasta das worktrees que o ork cria agora nasce fora do git.
+    const pastaDasWorktrees = path.dirname(dir);
+    const pastaNova = !fs.existsSync(pastaDasWorktrees);
     // Branch nova (`-b`) no caso comum; branch que ja existe no ciclo `merge-branch`.
     const argumentos = opcoes.branchExistente
         ? ['worktree', 'add', dir, opcoes.branchExistente]
@@ -152,6 +214,8 @@ function criarWorktree(carregado, id, slug, opcoes = {}) {
     if (!r.ok) {
         throw new Error(`git worktree add falhou: ${(r.stderr || r.stdout).trim()}`);
     }
+    if (pastaNova)
+        (0, util_1.ignorarPastaNoGit)(pastaDasWorktrees, (0, estado_thread_1.raizDoEstado)(raiz));
     const lista = (0, util_1.exec)('git', ['worktree', 'list', '--porcelain'], raiz);
     const criada = lista.ok && lista.stdout.split('\n').some((l) => l.trim() === `worktree ${dir}`);
     if (!criada) {
@@ -160,6 +224,105 @@ function criarWorktree(carregado, id, slug, opcoes = {}) {
     (0, estado_thread_1.vincularEstado)(raiz, id, dir);
     return { dir, branch };
 }
+/**
+ * Resolve `--worktree`, `--sem-worktree` e `worktree.por_thread`. As flags vencem a chave; as duas juntas, ou
+ * `--sem-worktree` com valor (o parser leva o argumento seguinte), sao erro de uso. `--worktree` sozinho ou `auto`
+ * cria a worktree; outro texto e um diretorio que ja existe, como antes.
+ */
+function pedidoDeWorktree(flags, porThread) {
+    const worktree = flags.worktree === false ? undefined : flags.worktree;
+    if (typeof worktree === 'string' && !worktree.trim())
+        throw new Error('uso: --worktree pede auto ou um diretório que já existe');
+    if (typeof flags.semWorktree === 'string') {
+        throw new Error(`uso: --sem-worktree não leva valor (recebeu "${flags.semWorktree}")`);
+    }
+    const semWorktree = flags.semWorktree === true;
+    if (semWorktree && worktree !== undefined)
+        throw new Error('uso: --worktree e --sem-worktree se excluem; use um dos dois');
+    if (semWorktree)
+        return { criar: false, dir: null, origem: 'sem-worktree' };
+    if (worktree === true || worktree === 'auto')
+        return { criar: true, dir: null, origem: 'flag' };
+    if (typeof worktree === 'string')
+        return { criar: false, dir: worktree, origem: 'diretorio' };
+    return porThread ? { criar: true, dir: null, origem: 'chave' } : { criar: false, dir: null, origem: 'nenhuma' };
+}
+/**
+ * P4 do ensaio da 0.5.0: a linha que diz de onde veio a worktree da thread nova. Na criacao, so quando ela veio da
+ * chave (quem passou `--worktree auto` sabe de onde ela veio); no `--dry-run`, para qualquer origem.
+ */
+function linhaDaWorktree(por, gravada, variante) {
+    if (!por || (gravada && por !== 'chave'))
+        return null;
+    const verbo = gravada ? 'criada' : 'seria criada';
+    if (por === 'chave') {
+        return `  worktree: ${verbo} pela chave worktree.por_thread do orkastery.yaml; para criar sem ela, use --sem-worktree`;
+    }
+    if (por === 'flag')
+        return `  worktree: ${verbo} pelo --worktree auto`;
+    return `  worktree: ${verbo} pelo ciclo ${variante ?? 'da thread'}, que exige worktree isolada`;
+}
+/**
+ * P4 do ensaio da 0.5.0: o que acontece no SHIP com a thread criada por `--sem-worktree`. O `ork ship` entrega a
+ * branch em que a raiz estava na criacao (`thread.base.branch`), e a policy `push_direto_na_base` do manifesto barra
+ * (`block`), avisa (outro valor) ou deixa passar (sem ela, ou `off`) a entrega de uma branch para ela mesma ou da
+ * base. Raiz fora de branch (HEAD destacado ou repositorio sem commit) nao tem branch de origem.
+ */
+function avisoDeThreadSemWorktree(thread, manifesto, gravada = true) {
+    const base = manifesto.worktree.base_branch;
+    const branch = thread.base.branch;
+    const inicio = gravada
+        ? `Aviso: thread ${thread.id} sem worktree (--sem-worktree): ela trabalha na raiz do projeto`
+        : `Aviso: sem worktree (--sem-worktree), a thread ${thread.id} trabalharia na raiz do projeto`;
+    const ensure = `Antes do GO, ork worktree ensure ${thread.id} cria a worktree e a branch da thread`;
+    if (thread.base.commit === util_1.COMMIT_DESCONHECIDO) {
+        // Sem commit, nem o `ork worktree ensure` tem de onde partir: o caminho e o do aviso de thread sem base.
+        return `${inicio}, num repositório ainda sem commit, fora de qualquer branch, e o ork ship não tem branch de origem ` +
+            'para entregar. Faça o primeiro commit e siga o aviso de thread sem base.';
+    }
+    if (branch === 'HEAD') {
+        return `${inicio}, com o HEAD destacado, fora de qualquer branch, e o ork ship não tem branch de origem para entregar. ${ensure}.`;
+    }
+    if (branch !== base) {
+        return `${inicio}, na branch ${branch}, e o ork ship entrega essa branch como estiver, com o que mais entrar nela; ` +
+            `com --para ${branch}, a entrega vira push direto, que a policy push_direto_na_base confere. ${ensure}.`;
+    }
+    const policy = manifesto.policies?.push_direto_na_base;
+    const efeito = policy === 'block'
+        ? 'o ork ship barra a entrega por push_direto_na_base (block): não há branch de thread para mergear'
+        : policy === undefined || policy === 'off'
+            ? 'o ork ship empurra a base direto, sem branch de thread (push_direto_na_base desligada)'
+            : `o ork ship avisa push_direto_na_base (${policy}) e empurra a base direto, sem branch de thread`;
+    return `${inicio}, na branch base ${base}, e ${efeito}. ${ensure}; depois do GO, os commits já estão na base e o ship não os separa.`;
+}
+/**
+ * P4 do ensaio da 0.5.0 (CHECK): no `--dry-run`, por que a criacao de verdade recusaria a worktree, em vez de preve-la.
+ * O ciclo que exige worktree nao aceita `--sem-worktree`, entao a saida so e sugerida para a chave e a flag.
+ */
+function avisoDeWorktreeQueFalharia(f) {
+    const semWorktree = f.por === 'ciclo' ? '' : ' ou crie com --sem-worktree';
+    if (f.motivo === 'pasta-existe') {
+        return `Aviso: a pasta ${f.dir} já existe, e a criação de verdade recusaria a worktree da thread: tire a pasta${semWorktree}.`;
+    }
+    if (f.motivo === 'branch-existe') {
+        return `Aviso: a branch ${f.branch} já existe, e a criação de verdade recusaria a worktree da thread: tire a branch${semWorktree}.`;
+    }
+    return 'Aviso: o repositório ainda não tem commit, e a criação de verdade recusaria a worktree da thread no git worktree add: ' +
+        'faça o primeiro commit antes.';
+}
+/** P4 do ensaio da 0.5.0: a worktree que a chave pede nao tem de onde partir num repositorio sem commit. */
+function avisoDeChaveSemCommit(gravada) {
+    return 'Aviso: worktree.por_thread pede a worktree da thread, mas o repositório ainda não tem commit: ' +
+        `a thread ${gravada ? 'nasceu' : 'nasceria'} na raiz do projeto, sem worktree.`;
+}
+/** P4: o aviso de worktree do `ork thread new`, para o stderr, ou `null` quando nao ha o que avisar. */
+function avisoDaWorktree(origem, resultado, manifesto) {
+    if (origem === 'sem-worktree')
+        return avisoDeThreadSemWorktree(resultado.thread, manifesto, resultado.gravada);
+    if (origem === 'chave' && !resultado.worktreePor)
+        return avisoDeChaveSemCommit(resultado.gravada);
+    return null;
+}
 /** Cria a thread: valida modo contra o manifesto, gera o slug e carimba a base. */
 function novaThread(carregado, opcoes) {
     if (opcoes.dryRun)
@@ -217,6 +380,13 @@ function criarThreadSerializada(carregado, opcoes) {
     else if (opcoes.branch) {
         throw new Error('--branch so vale com --ciclo merge-branch');
     }
+    // `greenfield`, `merge-branch` e `feature-xl-faseada` exigem worktree isolada: sao os
+    // ciclos que escrevem codigo em paralelo com outras threads.
+    const exigeWorktree = variante ? (0, ciclos_1.definicaoDaVariante)(variante).exigeWorktree : false;
+    // P4 do ensaio da 0.5.0 (D4): o ciclo que exige worktree nao nasce sem ela, e a recusa sai antes de gravar.
+    if (exigeWorktree && opcoes.origemDaWorktree === 'sem-worktree') {
+        throw new Error(`o ciclo ${variante} exige worktree isolada: crie a thread sem --sem-worktree ou escolha outro ciclo`);
+    }
     const reservation = opcoes.reservation;
     const operation = reservation ? (0, creation_operation_store_1.readCreationOperation)(raiz, reservation.operationId, reservation.principal) : null;
     if (operation && (!operation.reserved.threadIds.includes(reservation.threadId)
@@ -241,11 +411,11 @@ function criarThreadSerializada(carregado, opcoes) {
         && fs.readdirSync(dirThread(raiz, reservation.threadId)).some((name) => !/^\.thread\.json\..+\.tmp$/.test(name))) {
         throw new Error('creation.conflict: diretório reservado sem origem confirmada');
     }
+    // P4 do ensaio da 0.5.0 (CHECK): o ensaio usa o mesmo id livre da criacao (o `idDisponivel` so le o disco), para a
+    // worktree que ele mostra ser a que a criacao usaria.
     const { id, assunto } = reservation
         ? { id: reservation.threadId, assunto: reservation.threadId.slice(abbrev.length + 1) }
-        : opcoes.dryRun
-            ? { id: `${abbrev}-${assuntoBruto}`, assunto: assuntoBruto }
-            : idDisponivel(raiz, abbrev, assuntoBruto);
+        : idDisponivel(raiz, abbrev, assuntoBruto);
     const slug = opcoes.slug ?? (0, slug_1.montarSlug)(abbrev, assunto, blocos[0].slugFases);
     // O override `--slug` do builder tambem passa pela regex canonica.
     if (!(0, slug_1.slugValido)(slug)) {
@@ -281,13 +451,38 @@ function criarThreadSerializada(carregado, opcoes) {
     };
     if (variante === 'feature-xl-faseada')
         thread.fatias = opcoes.fatias ?? 3;
-    if (opcoes.dryRun)
-        return { thread, gravada: false };
+    // P4 do ensaio da 0.5.0: por que a thread ganha a worktree. O ensaio e a chave preveem a worktree antes; a pedida
+    // por flag ou por ciclo segue direto ao git, como era. A pedida so pela chave espera o primeiro commit (D3): sem
+    // commit, a thread fica na raiz, como antes. O ciclo que exige worktree vence a chave e a flag na origem: a worktree
+    // e dele, e o `--sem-worktree` que a linha da chave sugeriria ele recusa (CHECK, rodada 2).
+    const pedeWorktree = opcoes.criarWorktree === true || exigeWorktree;
+    const pelaChave = opcoes.criarWorktree === true && opcoes.origemDaWorktree === 'chave';
+    const prevista = pedeWorktree && (opcoes.dryRun || pelaChave)
+        ? worktreePrevista(carregado, id, slug, { branchExistente: opcoes.branch }) : null;
+    const worktreePor = !pedeWorktree || (pelaChave && !exigeWorktree && prevista?.falha === 'sem-commit') ? null
+        : exigeWorktree ? 'ciclo' : pelaChave ? 'chave' : 'flag';
+    if (opcoes.dryRun) {
+        // P4 (D8): o ensaio mostra a worktree que a criacao usaria; quando ela recusaria, diz por que, em vez de preve-la.
+        if (worktreePor && prevista?.falha) {
+            return { thread, gravada: false, worktreePor: null,
+                worktreeFalharia: { motivo: prevista.falha, dir: prevista.dir, branch: prevista.branch, por: worktreePor } };
+        }
+        if (worktreePor && prevista?.commit) {
+            thread.worktree = prevista.dir;
+            thread.base = { branch: prevista.branch, commit: prevista.commit };
+        }
+        return { thread, gravada: false, worktreePor };
+    }
+    // P4 (CHECK): a worktree pedida so pela chave, com a pasta ou a branch ja ocupadas, recusa dizendo de onde veio o
+    // pedido e qual e a saida.
+    const ocupadaPelaChave = pelaChave && !exigeWorktree && prevista &&
+        (prevista.falha === 'pasta-existe' || prevista.falha === 'branch-existe') ? prevista : null;
+    if (ocupadaPelaChave) {
+        const qual = ocupadaPelaChave.falha === 'pasta-existe' ? `a pasta ${ocupadaPelaChave.dir}` : `a branch ${ocupadaPelaChave.branch}`;
+        throw new Error(`${qual} já existe, e a chave worktree.por_thread pede a worktree da thread: tire-a ou crie com --sem-worktree`);
+    }
     let worktreeCriada = null;
-    // `greenfield`, `merge-branch` e `feature-xl-faseada` exigem worktree isolada: sao os
-    // ciclos que escrevem codigo em paralelo com outras threads.
-    const exigeWorktree = variante ? (0, ciclos_1.definicaoDaVariante)(variante).exigeWorktree : false;
-    if (opcoes.criarWorktree || exigeWorktree) {
+    if (worktreePor) {
         worktreeCriada = criarWorktree(carregado, id, slug, {
             branchExistente: opcoes.branch,
         });
@@ -309,6 +504,8 @@ function criarThreadSerializada(carregado, opcoes) {
         base: thread.base,
         projeto: manifesto.project.name,
         worktree: thread.worktree,
+        // P4 do ensaio da 0.5.0 (D9): quem abriu a thread sem worktree de proposito fica no rastro.
+        ...(opcoes.origemDaWorktree === 'sem-worktree' ? { semWorktree: true } : {}),
         variante,
         branchDeOrigem: opcoes.branch ?? null,
         maquina: thread.maquina,
@@ -319,10 +516,11 @@ function criarThreadSerializada(carregado, opcoes) {
             dir: worktreeCriada.dir,
             branch: worktreeCriada.branch,
             base: manifesto.worktree.base_branch,
+            origem: worktreePor,
             fonte: 'git worktree list --porcelain',
         });
     }
-    return { thread, gravada: true };
+    return { thread, gravada: true, worktreePor };
 }
 /**
  * O bloco de loop que conduz a fase DESTA thread.
@@ -362,7 +560,7 @@ function resumoDaThread(thread, conducao) {
     linhas.push(`  ciclo     ${thread.variante ?? 'padrao do modo'}`);
     linhas.push(`  fase      ${thread.faseAtual}`);
     linhas.push(`  status    ${thread.status}`);
-    linhas.push(`  base      ${thread.base.branch} @ ${thread.base.commit.slice(0, 8)}`);
+    linhas.push(`  base      ${thread.base.branch} @ ${(0, util_1.shaCurto)(thread.base.commit)}`);
     linhas.push(`  worktree  ${thread.worktree ?? '(raiz do projeto)'}`);
     // I-36 (T17): quem passa a leitura da conducao ve a linha unica; sem ela o resumo fica como era.
     if (conducao !== undefined)