@bbliong/aimp 0.2.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.2.0-beta.1 — unreleased
+
+- Rebuilt sync around Git porcelain NUL records and explicit path policy.
+- Added recoverable transactions, immutable payloads, safe-copy checks, branch guards, and state migration.
+- Added Linux/WSL beta TUI with wrapped scrolling, fragmented mouse input, and command/path completion.
+- Removed automatic credential sanitization from the active workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aimp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# aimp
+
+AIMP (AI Mirror Project) adalah CLI lokal untuk bekerja dengan AI pada repo mirror terpisah. AI mengedit mirror, pengguna meninjau laporan dan perubahan, kemudian AIMP menerapkan batch yang disetujui ke project original. AIMP tidak memanggil model, tidak menjalankan aplikasi, tidak membuat commit di original, dan tidak melakukan push.
+
+## Install
+
+```bash
+npm install -g @bbliong/aimp@beta
+cd /path/to/original-project
+aimp
+```
+
+Node.js 22.14+ dan Git 2.34+ diperlukan. Linux dan WSL2 pada filesystem Linux adalah platform beta. Untuk terminal tanpa TUI, gunakan `aimp --plain status --json`.
+
+## Workflow
+
+1. Jalankan `/init` dari original. AIMP membuat repo mirror independen untuk branch aktif.
+2. Buka mirror dengan harness atau AI pilihan Anda. AIMP membuat `AGENTS-AIMP.md` dan `AIMP_REPORT.md`.
+3. AI mengedit mirror dan mengisi laporan dengan `Status: ready`.
+4. Dari original, jalankan `/status`, `/diff`, lalu `/sync`. Tinjau path, penghapusan, dan konfirmasi. File diterapkan ke original tanpa commit original; checkpoint lokal dibuat di mirror dengan pesan `(synced)`.
+5. Commit perubahan original dengan workflow project Anda. Untuk memperbarui mirror dari commit original, gunakan `/sync-original-to-ai` setelah original bersih.
+
+Perintah penting: `/init`, `/reinit`, `/use`, `/status`, `/diff`, `/sync`, `/sync-original-to-ai`, `/serialize`, `/get-summary`, `/get-commit-message`, `/recover`, `/doctor`, `/language en|id`, `/help`, `/exit`.
+
+`.aimpignore` berada di root original dan menjadi pengecualian dua arah, termasuk untuk file yang sudah tracked. Polanya mengikuti Git:
+
+```gitignore
+*.env
+private/
+!private/example.env
+```
+
+File yang dikecualikan tidak disalin, dihapus, atau diterapkan. Gunakan placeholder sendiri untuk konfigurasi AI; AIMP tidak melakukan sanitasi credential otomatis. `AGENTS-AIMP.md` adalah instruksi untuk harness, bukan sandbox OS. Proses AI yang berjalan sebagai user yang sama tetap dapat membaca file lain menurut izin OS.
+
+Jika transaksi terhenti, jalankan `/recover` untuk melanjutkan atau `/recover rollback` untuk memulihkan backup. Jangan menghapus folder state sebelum recovery selesai. Detail kontrak, batas platform, dan rencana rilis ada di `docs/`.
+
+## Development
+
+```bash
+npm ci
+npm run verify
+npm pack --dry-run --json
+```
+
+Laporan bug: <https://github.com/bbliong/aimp.dev/issues>. Security report: lihat `SECURITY.md`.

package/SECURITY.md

@@ -0,0 +1,7 @@
+# Security policy
+
+AIMP is a local review and file synchronization tool. It is not a sandbox. An AI process running under the same OS account may access any file that account can access. Run untrusted agents in a separate OS account, container, VM, or other sandbox.
+
+Do not put real credentials in the AI mirror. Keep them in files excluded by `.aimpignore` and use placeholders in tracked files. AIMP does not promise to discover every secret.
+
+Report security issues privately through the repository security contact or a private GitHub security advisory. Do not publish credentials, private project content, or an unpatched exploit in an issue.

package/bin/aimp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/RELEASE.md

@@ -0,0 +1,9 @@
+# Release runbook
+
+1. Pastikan `package.json` version, `repository`, changelog, README, dan supported platforms benar.
+2. Jalankan `npm ci` dan `npm run verify` pada Node 22 dan 24.
+3. Review `npm pack --dry-run --json`, lalu install tarball ke prefix sementara.
+4. Push tag `v<version>` dari commit yang sudah diverifikasi. Workflow GitHub Actions menjalankan test dan publish beta melalui npm trusted publishing.
+5. Setelah smoke test `npm install -g @bbliong/aimp@beta` dan `npx @bbliong/aimp@beta --version`, dokumentasikan hasil pilot sebelum memindahkan dist-tag ke `latest`.
+
+Jangan memakai token publish pada job pull request. Versi yang sudah dipublikasikan tidak dapat digunakan ulang.

package/docs/USAGE_ID.md

@@ -0,0 +1,7 @@
+# Panduan singkat Bahasa Indonesia
+
+`aimp` membuat repo mirror lokal terpisah agar AI bekerja tanpa menyentuh file project original secara langsung. Jalankan dari original, gunakan `/init`, lalu buka folder mirror dengan AI pilihan Anda. Setelah pekerjaan selesai, AI mengisi `AIMP_REPORT.md` dan mengubah statusnya menjadi `ready`.
+
+Jalankan `/diff` untuk meninjau path, kemudian `/sync` untuk menyalin batch yang disetujui ke original. AIMP tidak membuat commit di original. Commit checkpoint hanya dibuat di mirror dan diberi akhiran `(synced)`. Gunakan `/recover` jika proses terputus.
+
+Buat `.aimpignore` di original untuk file yang tidak boleh masuk mirror atau sync, misalnya `.env`, database lokal, dan credential. File ini berlaku untuk tracked maupun untracked.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@bbliong/aimp",
+  "version": "0.2.0-beta.1",
+  "description": "Manual Git-based AI workspace mirrors with reviewed sync and recoverable local checkpoints",
+  "type": "module",
+  "bin": {
+    "aimp": "bin/aimp.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/USAGE_ID.md",
+    "docs/RELEASE.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "scripts": {
+    "start": "node bin/aimp.js",
+    "test": "node --test test/*.test.js",
+    "lint": "eslint src bin test scripts --max-warnings=0",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:terminal": "python3 scripts/terminal-test.py",
+    "test:package": "node scripts/package-test.js",
+    "bench": "node scripts/benchmark.js",
+    "verify": "npm run lint && npm run typecheck && npm test && npm run test:terminal && npm run test:package",
+    "prepublishOnly": "npm run verify && node scripts/release-check.js"
+  },
+  "keywords": [
+    "ai",
+    "git",
+    "cli",
+    "workflow"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bbliong/aimp.dev.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bbliong/aimp.dev/issues"
+  },
+  "homepage": "https://github.com/bbliong/aimp.dev#readme",
+  "dependencies": {
+    "ink": "^5.2.1",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.2",
+    "eslint": "^10.10.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}

package/src/cli.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { git, text, branch, status, metrics } from './core/git.js';
+import { canonical } from './core/files.js';
+import { loadState, saveState, stateRoot, findMirror, withLock, loadJournal, migrate, newState } from './core/state.js';
+import { policy } from './core/policy.js';
+import { requirePair, changes, preparePlan, readReport, transact, recover, validateRepository } from './core/engine.js';
+import { initialize, recoverInitialization, useBranch } from './core/projects.js';
+
+const pkg = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
+export const originalCommands = ['/init', '/reinit', '/use', '/status', '/diff', '/sync', '/sync-original-to-ai', '/get-summary', '/get-commit-message', '/list', '/log', '/doctor', '/recover', '/migrate', '/adopt-baseline', '/adopt-policy', '/language', '/help', '/exit'];
+export const mirrorCommands = ['/serialize', '/status', '/diff', '/get-summary', '/get-commit-message', '/language', '/help', '/exit'];
+export const safeText = value => String(value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, c => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+const descriptions = {
+  '/init': ['Create an independent mirror for the current branch.', 'Buat mirror independen untuk branch aktif.'],
+  '/reinit': ['Replace or relocate the shared mirror, retaining a backup.', 'Ganti atau pindahkan mirror bersama, dengan backup.'],
+  '/use': ['Explicitly switch the mirror to the original branch.', 'Pindahkan mirror ke branch original secara eksplisit.'],
+  '/status': ['Inspect paths, branches, working changes, and pending commits.', 'Periksa folder, branch, perubahan file, dan commit pending.'],
+  '/diff': ['Preview changed paths and text diff; no file writes.', 'Preview path dan diff teks; tanpa menulis file.'],
+  '/sync': ['Review AI changes, apply to original, checkpoint AI only.', 'Review perubahan AI, terapkan ke original, checkpoint hanya AI.'],
+  '/sync-original-to-ai': ['Refresh the mirror from a clean original.', 'Perbarui mirror dari original yang bersih.'],
+  '/serialize': ['Adopt selected changes as a local mirror baseline; no sanitizing.', 'Jadikan perubahan terpilih baseline mirror lokal; tanpa sanitasi.'],
+  '/recover': ['Resume an interrupted operation; /recover rollback restores backups.', 'Lanjutkan transaksi terhenti; /recover rollback memulihkan backup.'],
+  '/migrate': ['Back up and migrate legacy state, then review the baseline.', 'Backup dan migrasi state lama, lalu review baseline.'],
+  '/adopt-baseline': ['Acknowledge the reviewed legacy baseline without discarding changes.', 'Setujui baseline lama yang sudah ditinjau tanpa membuang perubahan.'],
+  '/adopt-policy': ['Review and adopt the current .aimpignore policy.', 'Review dan setujui kebijakan .aimpignore saat ini.'],
+  '/doctor': ['Check repository shape, registry, Git, branch and recovery readiness.', 'Periksa repo, registry, Git, branch, dan kesiapan recovery.'],
+  '/get-summary': ['Read the ready report summary.', 'Baca ringkasan laporan yang ready.'],
+  '/get-commit-message': ['Read the proposed commit subject.', 'Baca usulan pesan commit.'],
+  '/list': ['List branch pairs and mirror locations.', 'Daftar pasangan branch dan lokasi mirror.'],
+  '/log': ['Show recent transaction receipts.', 'Tampilkan riwayat transaksi terbaru.'],
+  '/language': ['Set language: /language en|id.', 'Atur bahasa: /language en|id.'],
+  '/help': ['Show commands available in this workspace.', 'Tampilkan command yang tersedia di workspace ini.'],
+  '/exit': ['Exit and restore the previous terminal screen.', 'Keluar dan kembalikan layar terminal sebelumnya.'],
+};
+export const localized = (language, en, id) => language === 'id' ? id : en;
+export function tokenize(value) {
+  const tokens = []; let current = '', quote = null, escaped = false, started = false;
+  for (const c of value) {
+    if (escaped) { current += c; escaped = false; started = true; }
+    else if (c === '\\' && quote !== "'") escaped = true;
+    else if (quote) { if (c === quote) quote = null; else current += c; }
+    else if (c === '"' || c === "'") { quote = c; started = true; }
+    else if (/\s/.test(c)) { if (started) tokens.push(current); current = ''; started = false; }
+    else { current += c; started = true; }
+  }
+  if (quote || escaped) throw new Error('Unclosed quote or escape.');
+  if (started) tokens.push(current);
+  return tokens;
+}
+export async function pathCompleter(value) {
+  const expanded = value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : value;
+  const slash = expanded.lastIndexOf('/'), dir = slash < 0 ? '.' : expanded.slice(0, slash + 1), prefix = expanded.slice(slash + 1);
+  try { const entries = await fs.readdir(dir, { withFileTypes: true }); return [entries.filter(e => e.isDirectory() && e.name.startsWith(prefix)).map(e => `${slash < 0 ? '' : dir}${e.name}/`).sort(), value]; }
+  catch { return [[], value]; }
+}
+export async function context(start) {
+  if (process.platform !== 'linux') throw new Error('This beta supports Linux and WSL2 Linux filesystems.');
+  const root = await canonical(await text(start, ['rev-parse', '--show-toplevel']));
+  const original = await findMirror(root);
+  return { root, original: original || root, mode: original ? 'mirror' : 'original' };
+}
+export async function inspect(ctx, state) {
+  const currentBranch = await branch(ctx.root), stateBranch = ctx.mode === 'mirror' ? currentBranch : await branch(ctx.original);
+  const pair = state?.pairs?.[stateBranch];
+  const info = { mode: ctx.mode, original: ctx.original, mirror: pair?.mirror || null, branch: stateBranch, mirrorBranch: null, state: 'NOT_INITIALIZED', files: [], originalDirty: false, aiPending: false, committedPaths: 0 };
+  if (!pair) return info;
+  info.mirrorBranch = await branch(pair.mirror);
+  const active = state.pairs[info.mirrorBranch];
+  if (!active) { info.state = 'BRANCH_MISMATCH'; return info; }
+  const result = await changes(pair.mirror, active, await policy(ctx.original));
+  info.files = result.changes.map(e => `${e.kind}\t${JSON.stringify(e.path)}`);
+  info.aiPending = result.changes.length > 0; info.committedPaths = result.committed;
+  info.originalDirty = (await status(ctx.original)).length > 0;
+  info.state = await loadJournal(ctx.original) ? 'RECOVERY_REQUIRED' : info.mirrorBranch !== stateBranch ? 'BRANCH_MISMATCH' : pair.baselineNeedsReview ? 'BASELINE_UNKNOWN' : info.aiPending ? 'AI_PENDING' : 'CLEAN';
+  return info;
+}
+export function createSession(ctx, { output = console.log, prompt = async () => { throw new Error('Interactive confirmation requires a TTY.'); }, signal, profile = false } = {}) {
+  const emit = value => output(safeText(value));
+  async function execute(command) {
+    const tokens = Array.isArray(command) ? command : tokenize(command), raw = tokens.shift() || '', name = raw.startsWith('/') ? raw : `/${raw}`;
+    const started = performance.now(), calls = metrics.calls, gitTime = metrics.milliseconds;
+    let state = await loadState(ctx.original), language = state?.language || 'en';
+    const t = (en, id) => localized(language, en, id);
+    const confirm = async message => (await prompt(`${message} [y/N] `, { kind: 'confirm' })).trim().toLowerCase() === 'y';
+    const allowed = ctx.mode === 'mirror' ? mirrorCommands : originalCommands;
+    if (name === '/exit' || name === '/quit') return { exit: true };
+    if (name === '/help') { emit(allowed.map(k => `${k.padEnd(24)} ${descriptions[k][language === 'id' ? 1 : 0]}`).join('\n')); return {}; }
+    if (!allowed.includes(name)) throw new Error(name === '/resolve' ? 'Automatic merge was removed. Review and edit files manually before /sync.' : `Command unavailable in ${ctx.mode} mode: ${name}`);
+    const mutating = ['/init', '/reinit', '/use', '/sync', '/sync-original-to-ai', '/serialize', '/recover', '/migrate', '/adopt-baseline', '/adopt-policy', '/language'].includes(name) && !tokens.includes('--dry-run');
+    const run = async () => {
+      // Always reload after taking the project lock.
+      state = await loadState(ctx.original); language = state?.language || 'en';
+      if (mutating && name !== '/recover' && await loadJournal(ctx.original)) throw new Error('RECOVERY_REQUIRED: run /recover.');
+      if (state?.schemaVersion === 2 && mutating && !['/migrate', '/recover'].includes(name)) throw new Error('Legacy state detected. Run /migrate first.');
+      if (name === '/language') {
+        if (!['en', 'id'].includes(tokens[0])) throw new Error('Usage: /language en|id');
+        state ||= newState(ctx.original); state.language = tokens[0]; await saveState(ctx.original, state); emit(`Language: ${tokens[0]}`); return { language: tokens[0] };
+      }
+      if (name === '/migrate') {
+        if (!state || state.schemaVersion === 3) { emit(t('State is current.', 'State sudah terbaru.')); return {}; }
+        if (!await confirm(t('Back up legacy state (which may contain credentials) and migrate?', 'Backup state lama (mungkin berisi credential) lalu migrasikan?'))) return {};
+        const result = await migrate(ctx.original, state); emit(`Backup: ${result.backup}\n/adopt-baseline`); return {};
+      }
+      if (name === '/recover') {
+        const tx = await loadJournal(ctx.original); if (!tx) { emit(t('No recovery needed.', 'Tidak ada recovery.')); return {}; }
+        if (!await confirm(t(`Recover transaction ${tx.id} (${tokens[0] || 'resume'})?`, `Pulihkan transaksi ${tx.id} (${tokens[0] || 'resume'})?`))) return {};
+        if (tx.kind === 'initialize') await recoverInitialization(ctx.original, tx); else await recover(ctx.original, tokens[0]);
+        emit(t('Recovery complete.', 'Recovery selesai.')); return {};
+      }
+      if (name === '/init' || name === '/reinit') {
+        state ||= newState(ctx.original);
+        const b = await branch(ctx.original), pair = state.pairs[b];
+        if (pair && name === '/init') { await useBranch(ctx.original, state); emit(`Mirror: ${pair.mirror}`); return {}; }
+        const existing = Object.values(state.pairs)[0];
+        const fallback = existing?.mirror || path.resolve(ctx.original, '..', `${path.basename(ctx.original)}-ai`);
+        const requested = tokens[0] || (await prompt(t(`Mirror folder [${fallback}]: `, `Folder mirror [${fallback}]: `), { kind: 'path' })).trim() || fallback;
+        const destination = requested.startsWith('~/') ? path.join(os.homedir(), requested.slice(2)) : requested;
+        const created = await initialize(ctx.original, state, destination, { confirm, replacing: name === '/reinit', signal });
+        if (created) emit(`Mirror: ${created.mirror}${created.backup ? `\nBackup: ${created.backup}` : ''}`);
+        return {};
+      }
+      if (name === '/status') {
+        const info = await inspect(ctx, state);
+        emit(tokens.includes('--json') ? JSON.stringify(info) : `Original: ${info.original}\nBranch: ${info.branch}\nAI copy: ${info.mirror || '—'}\nAI branch: ${info.mirrorBranch || '—'}\nOriginal dirty: ${info.originalDirty}\nAI pending: ${info.aiPending}\nCommitted paths since baseline: ${info.committedPaths}\nState: ${info.state}\n${info.files.join('\n')}`);
+        return { monitor: info };
+      }
+      if (name === '/doctor') {
+        const checks = { node: process.version, git: await text(ctx.root, ['--version']), stateRoot: stateRoot(), schema: state?.schemaVersion || null, platform: process.platform, sandbox: false };
+        try { await validateRepository(ctx.original); checks.original = 'ok'; if (state && Object.keys(state.pairs).length) await requirePair(ctx.original, state); checks.pair = 'ok'; } catch (e) { checks.problem = e.message; }
+        checks.recoveryRequired = Boolean(await loadJournal(ctx.original)); emit(JSON.stringify(checks, null, 2)); return {};
+      }
+      if (name === '/list') { emit(Object.entries(state?.pairs || {}).map(([b, p]) => `${b}\t${p.mirror}`).join('\n') || t('No mirrors.', 'Belum ada mirror.')); return {}; }
+      if (name === '/log') { emit(JSON.stringify(state?.history || [], null, 2)); return {}; }
+      if (name === '/use') { const pair = await useBranch(ctx.original, state); emit(`${pair.branch} → ${pair.mirror}`); return {}; }
+      const b = await branch(ctx.root), pair = state?.pairs?.[b];
+      if (!pair) throw new Error('Branch is not initialized. Run /init.');
+      if (name === '/adopt-baseline') {
+        await requirePair(ctx.original, state);
+        emit(`Original baseline: ${pair.baselineOriginal}\nMirror baseline: ${pair.baselineAi}`);
+        if (!await confirm(t('I reviewed these baselines; keep pending changes and enable sync?', 'Saya sudah memeriksa baseline; pertahankan perubahan pending dan aktifkan sync?'))) return {};
+        pair.baselineNeedsReview = false; pair.policyHash = (await policy(ctx.original)).hash; await saveState(ctx.original, state); return {};
+      }
+      if (name === '/adopt-policy') {
+        const rules = await policy(ctx.original);
+        emit(rules.content.toString('utf8') || '(empty .aimpignore)');
+        if (!await confirm(t('Adopt this policy? Re-included files require explicit reinit to restore skipped historical changes.', 'Setujui policy ini? File yang dimasukkan kembali membutuhkan reinit untuk perubahan historis yang pernah dilewati.'))) return {};
+        pair.policyHash = rules.hash; await saveState(ctx.original, state); return {};
+      }
+      if (name === '/get-summary' || name === '/get-commit-message') { const report = await readReport(pair.mirror, pair, state.projectId); emit(name === '/get-summary' ? report.summary : report.message); return {}; }
+      if (name === '/diff') {
+        const result = await changes(pair.mirror, pair, await policy(ctx.original));
+        emit(result.changes.map(e => `${e.kind}\t${JSON.stringify(e.path)}`).join('\n') || t('No changes.', 'Tidak ada perubahan.'));
+        for (const entry of result.changes) {
+          if ((entry.after?.size || 0) > 1024 * 1024) { emit(`${JSON.stringify(entry.path)}: large file; review externally.`); continue; }
+          emit((await git(pair.mirror, ['diff', '--no-ext-diff', '--no-textconv', pair.baselineAi, '--', entry.path])).stdout.toString('utf8'));
+        }
+        return {};
+      }
+      if (name === '/serialize') {
+        if (ctx.mode !== 'mirror') throw new Error('/serialize is only available in the mirror.');
+        const detected = await changes(pair.mirror, pair, await policy(ctx.original));
+        let selected = detected.changes;
+        emit(selected.map((f, i) => `${i + 1}. ${f.kind}\t${JSON.stringify(f.path)}`).join('\n'));
+        if (!selected.length) { emit(t('No changes.', 'Tidak ada perubahan.')); return {}; }
+        const selection = tokens.length ? tokens : tokenize(await prompt(t('Select exact paths (quote spaces), or * for all: ', 'Pilih path tepat (kutip spasi), atau * untuk semua: '), { kind: 'text' }));
+        if (!selection.includes('*')) { const wanted = new Set(selection); if ([...wanted].some(p => !selected.some(f => f.path === p))) throw new Error('Selection contains an unchanged or excluded path.'); selected = selected.filter(f => wanted.has(f.path)); }
+        if (!selected.length) return {};
+        if (!await confirm(t('Adopt these paths locally? This does not protect them from future refresh; use .aimpignore for that.', 'Jadikan path ini baseline lokal? Untuk melindunginya dari refresh berikutnya, gunakan .aimpignore.'))) return {};
+        const plan = await preparePlan(ctx.original, state);
+        plan.changes = selected.map(f => ({ ...f, before: f.after })); plan.direction = 'serialize'; plan.source = pair.mirror; plan.target = pair.mirror;
+        await transact(state, plan, `chore(aimp): serialize ${pair.branch}`, { signal }); emit(t('Local baseline adopted.', 'Baseline lokal diperbarui.')); return {};
+      }
+      if (name === '/sync' || name === '/sync-original-to-ai') {
+        const direction = name === '/sync' ? 'ai-to-original' : 'original-to-ai';
+        const plan = await preparePlan(ctx.original, state, direction);
+        if (tokens.includes('--dry-run')) { emit(JSON.stringify(plan, null, 2)); return { plan }; }
+        if (!plan.changes.length) { emit(t('No changes to sync.', 'Tidak ada perubahan untuk sync.')); return {}; }
+        const report = direction === 'ai-to-original' ? await readReport(pair.mirror, pair, state.projectId) : null;
+        const message = report ? `${report.message} (synced)` : `chore(aimp): refresh ${pair.branch}`;
+        if (report) emit(report.summary);
+        emit(plan.changes.map(f => `${f.kind}\t${JSON.stringify(f.path)}`).join('\n'));
+        const dirtyPaths = new Set((await status(ctx.original)).map(f => f.path));
+        const overlap = plan.changes.filter(f => dirtyPaths.has(f.path));
+        if (overlap.length) { emit(overlap.map(f => JSON.stringify(f.path)).join('\n')); if (!await confirm(t('Overwrite these uncommitted original paths?', 'Timpa path original di atas yang belum di-commit?'))) return {}; }
+        if (plan.changes.some(f => !f.after) && !await confirm(t('Approve the listed deletions?', 'Setujui penghapusan yang ditampilkan?'))) return {};
+        if (!await confirm(t('Apply these files and create a local AI checkpoint? Original remains uncommitted.', 'Terapkan file ini dan buat checkpoint lokal AI? Original tetap tanpa commit.'))) return {};
+        if (report && (await readReport(pair.mirror, pair, state.projectId)).hash !== report.hash) throw new Error('Report changed after preview.');
+        const result = await transact(state, plan, message, { signal }); emit(`Checkpoint AI: ${result.aiCommit}`); return {};
+      }
+      return {};
+    };
+    try { return mutating ? await withLock(ctx.original, run) : await run(); }
+    finally { if (profile) emit(JSON.stringify({ profile: name, machineAndPromptMs: Math.round(performance.now() - started), gitCalls: metrics.calls - calls, gitMs: Math.round(metrics.milliseconds - gitTime) })); }
+  }
+  return { execute, context: ctx, commands: ctx.mode === 'mirror' ? mirrorCommands : originalCommands };
+}
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes('--version') || argv.includes('-v')) { console.log(`aimp ${pkg.version}`); return; }
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('aimp — manual AI project mirror\nUsage: aimp [--plain] [--profile]\n       aimp status --json\n       aimp sync --dry-run\n\n' + originalCommands.map(c => `${c.padEnd(24)} ${descriptions[c][0]}`).join('\n')); return;
+  }
+  const ctx = await context(process.cwd()), plain = argv.includes('--plain') || !stdin.isTTY || !stdout.isTTY, profile = argv.includes('--profile');
+  const args = argv.filter(a => !['--plain', '--profile'].includes(a));
+  if (!plain && !args.length) { const { runInk } = await import('./ui.js'); await runInk({ ctx, profile }); return; }
+  const rl = stdin.isTTY ? createInterface({ input: stdin, output: stdout }) : null;
+  const controller = new AbortController(); const stop = () => controller.abort(); process.on('SIGINT', stop);
+  const session = createSession(ctx, { profile, signal: controller.signal, prompt: rl ? p => rl.question(p, { signal: controller.signal }) : undefined });
+  try {
+    if (args.length) { await session.execute(args); return; }
+    if (!rl) throw new Error('Use a command in non-interactive mode, e.g. aimp status --json.');
+    while (!controller.signal.aborted) {
+      const command = await rl.question(ctx.mode === 'mirror' ? 'aimp-ai> ' : 'aimp> ', { signal: controller.signal });
+      try { if ((await session.execute(command)).exit) break; } catch (e) { console.error(safeText(e.message)); }
+    }
+  } finally { rl?.close(); process.off('SIGINT', stop); }
+}
+export { loadState };
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(e => { console.error(safeText(e.message)); process.exitCode = 1; });

package/src/core/contracts.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+/** @typedef {{hash:string, oid:string, size:number, mode:number}} Fingerprint */
+/** @typedef {{path:string, kind:string, after:Fingerprint|null, before:Fingerprint|null}} Change */
+/** @typedef {{version:3, id:string, root:string, mirror:string, source:string, target:string,
+ * branch:string, direction:'ai-to-original'|'original-to-ai'|'serialize', originalHead:string,
+ * originalIndex:string|null, mirrorHead:string, mirrorIndex:string|null, policyHash:string,
+ * changes:Change[]}} Plan */
+
+/** @param {unknown} value @returns {value is Fingerprint|null} */
+function validFingerprint(value) {
+  if (value === null) return true;
+  if (typeof value !== 'object' || !value) return false;
+  const f = /** @type {Record<string, unknown>} */ (value);
+  return typeof f.hash === 'string' && /^[a-f0-9]{64}$/.test(f.hash) && typeof f.oid === 'string' && /^[a-f0-9]{40}$/.test(f.oid)
+    && typeof f.mode === 'number' && Number.isInteger(f.mode) && f.mode >= 0 && f.mode <= 0o777
+    && typeof f.size === 'number' && Number.isSafeInteger(f.size) && f.size >= 0;
+}
+/** Validate disk data before recovery performs any mutations.
+ * @param {unknown} input @returns {asserts input is Plan}
+ */
+export function validatePlan(input) {
+  if (typeof input !== 'object' || input === null) throw new Error('Invalid transaction plan.');
+  const p = /** @type {Record<string, unknown>} */ (input);
+  if (p.version !== 3 || typeof p.id !== 'string' || !/^[a-f0-9-]{36}$/.test(p.id)
+    || !['ai-to-original', 'original-to-ai', 'serialize'].includes(String(p.direction))
+    || ['root','mirror','source','target','branch'].some(k => typeof p[k] !== 'string' || !p[k])
+    || ['originalHead','mirrorHead'].some(k => !/^[a-f0-9]{40}$/.test(String(p[k])))
+    || !Array.isArray(p.changes)) throw new Error('Invalid transaction plan.');
+  const seen = new Set();
+  for (const file of p.changes) {
+    if (!file || typeof file.path !== 'string' || seen.has(file.path) || !validFingerprint(file.after) || !validFingerprint(file.before)) throw new Error('Invalid transaction file entry.');
+    seen.add(file.path);
+  }
+}

package/src/core/engine.js

@@ -0,0 +1,240 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { git, text, head, branch, status, names, tree, guardRepo } from './git.js';
+import { fingerprint, equal, gitMode, safePath, present, hash, copy, atomicJson, syncDirectory, canonical, overlaps } from './files.js';
+import { validatePlan } from './contracts.js';
+import { policy, included, guardAttributes } from './policy.js';
+import { stateRoot, saveJournal, loadJournal, clearJournal, saveState } from './state.js';
+
+export const REPORT = 'AIMP_REPORT.md';
+export const RULES = 'AGENTS-AIMP.md';
+export async function validateRepository(root) {
+  if (await canonical(root) !== root || !(await present(path.join(root, '.git')))?.isDirectory()) throw new Error('A regular repository with a canonical root is required.');
+  for (const name of ['rebase-apply', 'rebase-merge', 'sequencer', 'worktrees', 'objects/info/alternates']) if (await present(path.join(root, '.git', name))) throw new Error(`Unsupported Git repository state: ${name}`);
+  await guardRepo(root);
+}
+export async function requirePair(root, state) {
+  await validateRepository(root);
+  const name = await branch(root), pair = state?.pairs?.[name];
+  if (!pair) throw new Error('Branch is not initialized. Run /init.');
+  if (overlaps(root, pair.mirror)) throw new Error('Original and mirror roots overlap.');
+  await validateRepository(pair.mirror);
+  if (await branch(pair.mirror) !== name) throw new Error('BRANCH_MISMATCH: run /use after resolving pending mirror work.');
+  const exists = await git(pair.mirror, ['cat-file', '-e', `${pair.baselineAi}^{commit}`], { allowFailure: true });
+  if (exists.code !== 0 || (await git(pair.mirror, ['merge-base', '--is-ancestor', pair.baselineAi, 'HEAD'], { allowFailure: true })).code !== 0) throw new Error('BASELINE_UNKNOWN: mirror history changed; review and reinitialize explicitly.');
+  return pair;
+}
+export async function changes(root, pair, rules) {
+  const records = await status(root);
+  const byPath = new Map(records.map(record => [record.path, record]));
+  if (records.some(r => /U/.test(r.code) || ['AA', 'DD'].includes(r.code))) throw new Error('Resolve Git index conflicts first.');
+  const committed = await names(root, ['diff', '--no-ext-diff', '--no-renames', '--name-only', '-z', pair.baselineAi, 'HEAD']);
+  const candidates = await included([...committed, ...records.map(r => r.path), ...Object.keys(pair.acknowledgements || {})], rules);
+  const base = await tree(root, pair.baselineAi), result = [];
+  await guardAttributes(root, candidates);
+  for (const rel of candidates) {
+    const st = byPath.get(rel);
+    if (st && st.code[0] !== ' ' && st.code[0] !== '?' && st.code[1] !== ' ') throw new Error(`Partially staged path: ${JSON.stringify(rel)}. Stage or unstage it completely first.`);
+    const current = await fingerprint(root, rel);
+    const previous = Object.hasOwn(pair.acknowledgements || {}, rel) ? pair.acknowledgements[rel] : base.get(rel);
+    if (!current && !previous) continue;
+    if (current && previous && current.oid === previous.oid && gitMode(current) === previous.mode) continue;
+    if (previous?.type === 'commit') throw new Error('Submodules are not supported.');
+    result.push({ path: rel, after: current, kind: !current ? 'deleted' : !previous ? 'added' : 'modified' });
+  }
+  return { changes: result, records, committed: committed.length };
+}
+export function reportTemplate(id, name, batch) {
+  return `Mirror-ID: ${id}\nBranch: ${name}\nBatch-ID: ${batch}\nStatus: draft\n\n## Summary\n<!-- Describe the changes. -->\n\n## Commit Message\n<!-- One-line subject. -->\n\n## Tests\n<!-- Commands and results, or Not run: reason. -->\n\n## Notes\n<!-- Limitations, or None. -->\n`;
+}
+export async function writeMetadata(mirror, id, pair) {
+  const values = {
+    [REPORT]: reportTemplate(id, pair.branch, pair.batch),
+    [RULES]: `# AIMP workspace\n\nAIMP (AI Mirror Project) is a local tool for reviewing and manually synchronizing a separate AI workspace. This is the mirror for branch ${pair.branch}, not the original project.\n\n- Read and edit only this workspace. Do not access the original, parent directories, or credential stores.\n- These instructions are advisory, not an OS sandbox. Load this file manually if your harness does not discover it.\n- The user runs the original application and shares errors manually.\n- Do not push, add remotes, switch branches, reset history, or run synchronization commands.\n- Keep user placeholders intact. AIMP does not sanitize credentials automatically.\n- Complete AIMP_REPORT.md and set Status: ready after each batch. Report tests honestly.\n`,
+  };
+  for (const [rel, content] of Object.entries(values)) {
+    const target = await safePath(mirror, rel), tmp = `${target}.${crypto.randomUUID()}.tmp`;
+    await fs.writeFile(tmp, content, { mode: 0o644, flag: 'wx' }); await fs.rename(tmp, target);
+  }
+}
+export async function readReport(mirror, pair, id) {
+  const file = await safePath(mirror, REPORT);
+  if ((await fs.stat(file)).size > 1024 * 1024) throw new Error('Report is too large.');
+  const raw = await fs.readFile(file, 'utf8');
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(raw)) throw new Error('Report contains control characters.');
+  const field = name => raw.match(new RegExp(`^${name}: *(.*)$`, 'm'))?.[1].trim();
+  if (field('Mirror-ID') !== id || field('Branch') !== pair.branch || field('Batch-ID') !== pair.batch) throw new Error('Report identity does not match the active branch/batch.');
+  const sections = {};
+  for (const match of raw.matchAll(/^## (Summary|Commit Message|Tests|Notes)\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/gm)) sections[match[1]] = match[2].trim();
+  if (field('Status') !== 'ready' || ['Summary', 'Commit Message', 'Tests', 'Notes'].some(k => !sections[k] || sections[k].includes('<!--'))) throw new Error('Complete Summary, Commit Message, Tests and Notes, then set Status: ready.');
+  const message = sections['Commit Message'];
+  if (message.includes('\n') || message.length > 120) throw new Error('Commit Message must be one line, at most 120 characters.');
+  return { raw, hash: hash(raw), message, summary: sections.Summary };
+}
+export async function indexFingerprint(root) {
+  const p = path.join(root, '.git/index');
+  const st = await present(p);
+  if (!st) return null;
+  if (!st.isFile() || st.nlink !== 1) throw new Error('Unsupported Git index.');
+  return hash(await fs.readFile(p));
+}
+async function updateIndex(root, index, entries) {
+  const zero = '0'.repeat(40);
+  const input = entries.map(e => e.after ? `${gitMode(e.after)} ${e.after.oid}\t${e.path}\0` : `0 ${zero}\t${e.path}\0`).join('');
+  if (input) await git(root, ['update-index', '-z', '--index-info'], { env: { GIT_INDEX_FILE: index }, input });
+}
+export async function createCheckpoint(root, parent, entries, directory, message) {
+  const index = path.join(directory, 'checkpoint-index');
+  const env = { GIT_INDEX_FILE: index, GIT_AUTHOR_NAME: 'aimp', GIT_AUTHOR_EMAIL: 'aimp@local.invalid', GIT_COMMITTER_NAME: 'aimp', GIT_COMMITTER_EMAIL: 'aimp@local.invalid' };
+  await git(root, parent ? ['read-tree', parent] : ['read-tree', '--empty'], { env });
+  for (let i = 0; i < entries.length; i++) if (entries[i].after) {
+    const oid = await text(root, ['hash-object', '-w', '--no-filters', '--', path.join(directory, 'payload', String(i))]);
+    if (oid !== entries[i].after.oid) throw new Error('Payload checksum mismatch.');
+  }
+  await updateIndex(root, index, entries);
+  const treeId = await text(root, ['write-tree'], { env });
+  return text(root, ['commit-tree', treeId, ...(parent ? ['-p', parent] : [])], { env, input: `${message}\n` });
+}
+async function replaceIndex(root, tx, dir) {
+  if (await indexFingerprint(root) === tx.finalIndexHash) return;
+  const guard = path.join(root, '.git/index.lock'), handle = await fs.open(guard, 'wx', 0o600);
+  let renamed = false;
+  try {
+    if (await indexFingerprint(root) !== tx.mirrorIndex) throw new Error('Mirror index changed; recovery requires manual review.');
+    await handle.writeFile(await fs.readFile(path.join(dir, 'final-index'))); await handle.sync(); await handle.close();
+    await fs.rename(guard, path.join(root, '.git/index')); renamed = true;
+  } finally { if (!renamed) { await handle.close().catch(() => {}); await fs.rm(guard, { force: true }); } }
+}
+export async function preparePlan(root, state, direction = 'ai-to-original') {
+  const pair = await requirePair(root, state), rules = await policy(root);
+  if (pair.baselineNeedsReview) throw new Error('Migrated baseline needs review. Run /adopt-baseline after inspecting both repositories.');
+  if (pair.policyHash && pair.policyHash !== rules.hash) throw new Error('Ignore policy changed. Run /adopt-policy to review and accept it first.');
+  const detected = await changes(pair.mirror, pair, rules);
+  let files = detected.changes;
+  if (direction === 'original-to-ai') {
+    if ((await status(root)).length) throw new Error('Original has uncommitted changes. Commit or resolve them before reverse sync.');
+    if (files.length) throw new Error('Mirror has pending work. Sync or serialize it first.');
+    const originalBase = pair.baselineOriginal;
+    if (!originalBase || (await git(root, ['merge-base', '--is-ancestor', originalBase, 'HEAD'], { allowFailure: true })).code !== 0) throw new Error('Original baseline history changed. Reinitialize after review.');
+    const candidates = await included([...await names(root, ['diff', '--no-ext-diff', '--no-renames', '--name-only', '-z', originalBase, 'HEAD']), ...Object.keys(pair.applied || {})], rules);
+    await guardAttributes(root, candidates);
+    files = [];
+    for (const rel of candidates) {
+      const after = await fingerprint(root, rel), before = await fingerprint(pair.mirror, rel);
+      if (!equal(after, before)) files.push({ path: rel, after, kind: !after ? 'deleted' : !before ? 'added' : 'modified' });
+    }
+  }
+  const source = direction === 'ai-to-original' ? pair.mirror : root;
+  const target = direction === 'ai-to-original' ? root : pair.mirror;
+  for (const file of files) file.before = await fingerprint(target, file.path);
+  return { version: 3, id: crypto.randomUUID(), direction, root, source, target, branch: pair.branch,
+    mirror: pair.mirror, originalHead: await head(root), originalIndex: await indexFingerprint(root),
+    mirrorHead: await head(pair.mirror), mirrorIndex: await indexFingerprint(pair.mirror), policyHash: rules.hash, changes: files };
+}
+async function verifyPlan(tx) {
+  if (await branch(tx.root) !== tx.branch || await branch(tx.mirror) !== tx.branch || await head(tx.root) !== tx.originalHead || await head(tx.mirror) !== tx.mirrorHead || await indexFingerprint(tx.root) !== tx.originalIndex || await indexFingerprint(tx.mirror) !== tx.mirrorIndex || (await policy(tx.root)).hash !== tx.policyHash) throw new Error('Repository or policy changed after preview. Review a new plan.');
+  for (const file of tx.changes) {
+    if (!equal(await fingerprint(tx.source, file.path), file.after) || !equal(await fingerprint(tx.target, file.path), file.before)) throw new Error(`File changed after preview: ${JSON.stringify(file.path)}`);
+  }
+}
+export async function transact(state, plan, message, { fault = async () => {}, signal } = {}) {
+  validatePlan(plan);
+  if (await loadJournal(plan.root)) throw new Error('RECOVERY_REQUIRED: run /recover before another mutation.');
+  await verifyPlan(plan);
+  if (signal?.aborted) throw new Error('Cancelled.');
+  const dir = path.join(stateRoot(), 'transactions', plan.id);
+  await fs.mkdir(path.join(dir, 'payload'), { recursive: true, mode: 0o700 });
+  await fs.mkdir(path.join(dir, 'backup'), { recursive: true, mode: 0o700 });
+  const tx = { ...plan, stage: 'PREPARED', message, createdAt: new Date().toISOString() };
+  let journaled = false;
+  try {
+    for (let i = 0; i < tx.changes.length; i++) {
+      const file = tx.changes[i];
+      if (file.after) await copy(tx.source, file.path, dir, `payload/${i}`, file.after.mode);
+      if (file.before) await copy(tx.target, file.path, dir, `backup/${i}`, file.before.mode);
+      if (!equal(file.after, await fingerprint(dir, `payload/${i}`)) || !equal(file.before, await fingerprint(dir, `backup/${i}`))) throw new Error('Files changed while preparing transaction.');
+    }
+    await fault('CHECKPOINT_PREPARE');
+    tx.aiCommit = await createCheckpoint(tx.mirror, tx.mirrorHead, tx.changes, dir, message);
+    const finalIndex = path.join(dir, 'final-index');
+    await fs.copyFile(path.join(tx.mirror, '.git/index'), finalIndex);
+    await updateIndex(tx.mirror, finalIndex, tx.changes); tx.finalIndexHash = hash(await fs.readFile(finalIndex));
+    const next = structuredClone(state), pair = next.pairs[tx.branch];
+    pair.batch = crypto.randomUUID(); pair.policyHash = tx.policyHash;
+    if (tx.direction === 'serialize') {
+      for (const file of tx.changes) (pair.acknowledgements ||= {})[file.path] = file.after ? { oid: file.after.oid, mode: gitMode(file.after), type: 'blob' } : null;
+    } else {
+      pair.baselineAi = tx.aiCommit; pair.baselineOriginal = tx.originalHead;
+      for (const file of tx.changes) { delete (pair.acknowledgements ||= {})[file.path]; (pair.applied ||= {})[file.path] = file.after; }
+    }
+    next.history ||= []; next.history.push({ id: tx.id, branch: tx.branch, direction: tx.direction, ai: tx.aiCommit, originalBase: tx.originalHead, originalCommitted: false, message, at: tx.createdAt });
+    // Archive overflow independently, retaining a bounded active registry.
+    if (next.history.length > 200) { await atomicJson(path.join(dir, 'history-archive.json'), next.history.slice(0, -200)); next.history = next.history.slice(-200); }
+    tx.nextState = next;
+    await verifyPlan(tx); if (signal?.aborted) throw new Error('Cancelled.');
+    await saveJournal(tx.root, tx); journaled = true; await fault('PREPARED');
+    for (let i = 0; i < tx.changes.length; i++) {
+      if (signal?.aborted) throw new Error('Cancelled. Run /recover.');
+      const file = tx.changes[i];
+      if (!equal(await fingerprint(tx.target, file.path), file.before)) throw new Error('Target changed during apply.');
+      if (file.after) await copy(dir, `payload/${i}`, tx.target, file.path, file.after.mode);
+      else { await fs.rm(await safePath(tx.target, file.path), { force: true }); await syncDirectory(path.dirname(path.join(tx.target, file.path))); }
+      await fault(`FILE_${i}`);
+    }
+    tx.stage = 'ORIGINAL_APPLIED'; await saveJournal(tx.root, tx); await fault(tx.stage);
+    await finalize(tx, dir, fault);
+    return tx;
+  } catch (error) {
+    if (!journaled) await fs.rm(dir, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function finalize(tx, dir, fault = async () => {}) {
+  if (await branch(tx.root) !== tx.branch || await branch(tx.mirror) !== tx.branch || await head(tx.root) !== tx.originalHead || await indexFingerprint(tx.root) !== tx.originalIndex) throw new Error('Original Git state changed; review recovery.');
+  for (const file of tx.changes) if (!equal(await fingerprint(tx.target, file.path), file.after)) throw new Error('Applied files changed; review recovery before finalizing.');
+  const current = await head(tx.mirror);
+  if (current !== tx.aiCommit) {
+    if (current !== tx.mirrorHead || await indexFingerprint(tx.mirror) !== tx.mirrorIndex) throw new Error('Mirror HEAD/index changed.');
+    await git(tx.mirror, ['update-ref', `refs/heads/${tx.branch}`, tx.aiCommit, tx.mirrorHead]);
+  }
+  await fault('REF_UPDATED'); await replaceIndex(tx.mirror, tx, dir);
+  tx.stage = 'AI_CHECKPOINTED'; await saveJournal(tx.root, tx); await fault(tx.stage);
+  await saveState(tx.root, tx.nextState); await fault('STATE_SAVED');
+  await writeMetadata(tx.mirror, tx.nextState.projectId, tx.nextState.pairs[tx.branch]);
+  tx.stage = 'FINALIZED'; await saveJournal(tx.root, tx); await fault(tx.stage);
+  await clearJournal(tx.root);
+  // Retain only a compact receipt and any history archive after successful finalization.
+  await atomicJson(path.join(dir, 'receipt.json'), { id: tx.id, message: tx.message, aiCommit: tx.aiCommit, direction: tx.direction });
+  for (const name of ['payload', 'backup', 'checkpoint-index', 'final-index']) await fs.rm(path.join(dir, name), { recursive: true, force: true });
+}
+export async function recover(root, action = 'resume', options = {}) {
+  const tx = await loadJournal(root);
+  if (!tx) return null;
+  if (tx.version !== 3 || tx.root !== root || !/^[a-f0-9-]{36}$/.test(tx.id)) throw new Error('Legacy/invalid journal: automatic recovery is unavailable. Preserve backups for manual recovery.');
+  validatePlan(tx);
+  if (overlaps(root, tx.mirror) || tx.source !== (tx.direction === 'original-to-ai' ? root : tx.mirror) || tx.target !== (tx.direction === 'ai-to-original' ? root : tx.mirror)) throw new Error('Invalid recovery roots.');
+  if (await branch(root) !== tx.branch || await head(root) !== tx.originalHead || await indexFingerprint(root) !== tx.originalIndex || await branch(tx.mirror) !== tx.branch) throw new Error('Git state changed since interruption. Review recovery.');
+  if (!['resume', 'rollback'].includes(action)) throw new Error('Usage: /recover [resume|rollback]');
+  await validateRepository(root); await validateRepository(tx.mirror);
+  const dir = path.join(stateRoot(), 'transactions', tx.id);
+  if (action === 'rollback') {
+    if (await head(tx.mirror) !== tx.mirrorHead) throw new Error('Checkpoint already exists. Resume recovery instead of rolling back Git history.');
+    if (await branch(root) !== tx.branch || await head(root) !== tx.originalHead || await indexFingerprint(root) !== tx.originalIndex) throw new Error('Original Git state changed since the transaction.');
+    for (const file of tx.changes) { const actual = await fingerprint(tx.target, file.path); if (!equal(actual, file.before) && !equal(actual, file.after)) throw new Error(`New edits after interruption: ${JSON.stringify(file.path)}`); }
+    for (let i = 0; i < tx.changes.length; i++) {
+      const file = tx.changes[i];
+      if (file.before) { if (!equal(await fingerprint(dir, `backup/${i}`), file.before)) throw new Error('Backup checksum mismatch.'); await copy(dir, `backup/${i}`, tx.target, file.path, file.before.mode); }
+      else await fs.rm(await safePath(tx.target, file.path), { force: true });
+    }
+    await clearJournal(root); return { ...tx, rolledBack: true };
+  }
+  for (let i = 0; i < tx.changes.length; i++) {
+    const file = tx.changes[i], actual = await fingerprint(tx.target, file.path);
+    if (equal(actual, file.after)) continue;
+    if (!equal(actual, file.before)) throw new Error(`New edits after interruption: ${JSON.stringify(file.path)}`);
+    if (file.after) { if (!equal(await fingerprint(dir, `payload/${i}`), file.after)) throw new Error('Payload checksum mismatch.'); await copy(dir, `payload/${i}`, tx.target, file.path, file.after.mode); }
+    else await fs.rm(await safePath(tx.target, file.path), { force: true });
+  }
+  await finalize(tx, dir, options.fault); return tx;
+}

package/src/core/files.js

@@ -0,0 +1,81 @@
+import { promises as fs, constants } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export const MANAGED = new Set(['AIMP_REPORT.md', 'AGENTS-AIMP.md', 'AGENTS.md', '.aimpignore']);
+export const hash = data => crypto.createHash('sha256').update(data).digest('hex');
+export const present = async file => { try { return await fs.lstat(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
+export function validatePath(rel) {
+  const parts = rel.split('/');
+  if (!rel || path.isAbsolute(rel) || rel.includes('\0') || rel.includes('\\') || parts.some(p => !p || p === '.' || p === '..' || ['.git', '.aimp'].includes(p.toLowerCase()))) throw new Error(`Unsafe path: ${JSON.stringify(rel)}`);
+  return rel;
+}
+export async function safePath(root, rel) {
+  validatePath(rel);
+  let current = root;
+  const parts = rel.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    current = path.join(current, parts[i]);
+    const st = await present(current);
+    if (!st) continue;
+    if (st.isSymbolicLink() || (st.isFile() && st.nlink > 1)) throw new Error(`Link is not supported: ${JSON.stringify(rel)}`);
+    if (i < parts.length - 1) {
+      if (!st.isDirectory()) throw new Error(`Parent is not a directory: ${JSON.stringify(rel)}`);
+      if (await present(path.join(current, '.git'))) throw new Error(`Nested repository: ${JSON.stringify(rel)}`);
+    } else if (!st.isFile()) throw new Error(`Not a regular file: ${JSON.stringify(rel)}`);
+  }
+  return current;
+}
+export async function canonical(target) {
+  const absolute = path.resolve(target), st = await present(absolute);
+  if (st) { if (st.isSymbolicLink()) throw new Error('Root must not be a symlink.'); return fs.realpath(absolute); }
+  return path.join(await canonical(path.dirname(absolute)), path.basename(absolute));
+}
+export const overlaps = (a, b) => a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep);
+export async function mirrorTarget(original, requested, stateRoot) {
+  const target = await canonical(requested), home = await fs.realpath(os.homedir());
+  if (overlaps(original, target) || overlaps(stateRoot, target) || target === '/' || target === home || home.startsWith(target + path.sep)) throw new Error('Mirror target overlaps a protected directory.');
+  return target;
+}
+export async function fingerprint(root, rel) {
+  const full = await safePath(root, rel), st = await present(full);
+  if (!st) return null;
+  const file = await fs.open(full, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = await file.stat(), sha = crypto.createHash('sha256'), blob = crypto.createHash('sha1').update(`blob ${before.size}\0`);
+    for await (const chunk of file.createReadStream({ autoClose: false })) { sha.update(chunk); blob.update(chunk); }
+    const after = await file.stat();
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== after.ino) throw new Error(`File changed while reading: ${JSON.stringify(rel)}`);
+    return { hash: sha.digest('hex'), oid: blob.digest('hex'), size: before.size, mode: before.mode & 0o777 };
+  } finally { await file.close(); }
+}
+export const equal = (a, b) => a === b || Boolean(a && b && a.hash === b.hash && a.mode === b.mode);
+export const gitMode = info => info.mode & 0o111 ? '100755' : '100644';
+export async function copy(sourceRoot, sourceRel, targetRoot, targetRel, mode) {
+  const source = await safePath(sourceRoot, sourceRel), target = await safePath(targetRoot, targetRel);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const tmp = `${target}.aimp-${crypto.randomUUID()}.tmp`;
+  const src = await fs.open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let dest;
+  try {
+    dest = await fs.open(tmp, 'wx', 0o600);
+    const buffer = Buffer.allocUnsafe(256 * 1024);
+    for (;;) {
+      const { bytesRead } = await src.read(buffer, 0, buffer.length, null);
+      if (!bytesRead) break;
+      await dest.writeFile(buffer.subarray(0, bytesRead));
+    }
+    await dest.chmod(mode); await dest.sync(); await dest.close(); dest = null;
+    await safePath(targetRoot, targetRel);
+    await fs.rename(tmp, target); await syncDirectory(path.dirname(target));
+  } finally { await src.close(); if (dest) await dest.close(); await fs.rm(tmp, { force: true }); }
+}
+export async function syncDirectory(dir) { const handle = await fs.open(dir, 'r'); try { await handle.sync(); } finally { await handle.close(); } }
+export async function atomicJson(file, value) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  if ((await present(file))?.isSymbolicLink()) throw new Error('State file is a symlink.');
+  const tmp = `${file}.${crypto.randomUUID()}.tmp`, handle = await fs.open(tmp, 'wx', 0o600);
+  try { await handle.writeFile(JSON.stringify(value) + '\n'); await handle.sync(); } finally { await handle.close(); }
+  await fs.rename(tmp, file); await syncDirectory(path.dirname(file));
+}

package/src/core/git.js

@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+
+export const metrics = { calls: 0, milliseconds: 0 };
+export async function git(root, args, { input, env: extra = {}, allowFailure = false } = {}) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0',
+    GIT_OPTIONAL_LOCKS: '0', GIT_LITERAL_PATHSPECS: '1', LC_ALL: 'C', ...extra });
+  const started = performance.now(); metrics.calls++;
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = spawn('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'commit.gpgSign=false',
+        '-c', 'maintenance.auto=false', '-c', 'gc.auto=0', '-c', 'core.fsmonitor=false', ...args], { cwd: root, env, shell: false });
+      const stdout = [], stderr = []; let bytes = 0, timedOut = false;
+      const timer = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, 120_000);
+      child.stdout.on('data', chunk => { bytes += chunk.length; if (bytes > 128 * 1024 * 1024) child.kill(); else stdout.push(chunk); });
+      child.stderr.on('data', chunk => { if (stderr.length < 100) stderr.push(chunk); });
+      child.stdin.on('error', () => {});
+      child.once('error', error => { clearTimeout(timer); reject(error); });
+      child.once('close', code => {
+        clearTimeout(timer);
+        const result = { code, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr).toString('utf8') };
+        if (timedOut || bytes > 128 * 1024 * 1024) return reject(new Error('Git operation exceeded its time/output limit.'));
+        if (code !== 0 && !allowFailure) return reject(new Error(`Git ${args[0]} failed: ${result.stderr.trim() || code}`));
+        resolve(result);
+      });
+      child.stdin.end(input);
+    });
+  } finally { metrics.milliseconds += performance.now() - started; }
+}
+export const text = async (root, args, options) => (await git(root, args, options)).stdout.toString('utf8').trim();
+export const head = root => text(root, ['rev-parse', '--verify', 'HEAD']);
+export const branch = root => text(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+export function nul(buffer) {
+  const value = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+  if (value && !value.endsWith('\0')) throw new Error('Incomplete Git NUL output.');
+  return value ? value.slice(0, -1).split('\0') : [];
+}
+export function parseStatus(buffer) {
+  const records = nul(buffer), result = [];
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (record.length < 4 || record[2] !== ' ') throw new Error('Invalid Git status record.');
+    const code = record.slice(0, 2), name = record.slice(3);
+    result.push({ path: name, code });
+    if (/[RC]/.test(code)) {
+      if (!records[++i]) throw new Error('Incomplete Git rename record.');
+      result.push({ path: records[i], code: ' D' });
+    }
+  }
+  return result;
+}
+export const status = async root => parseStatus((await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'])).stdout);
+export const names = async (root, args) => nul((await git(root, args)).stdout);
+export async function tree(root, ref) {
+  const entries = new Map();
+  for (const row of await names(root, ['ls-tree', '-r', '-z', ref])) {
+    const tab = row.indexOf('\t'), [mode, type, oid] = row.slice(0, tab).split(' ');
+    entries.set(row.slice(tab + 1), { mode, type, oid });
+  }
+  return entries;
+}
+export async function guardRepo(root) {
+  if (await text(root, ['rev-parse', '--show-object-format']) !== 'sha1') throw new Error('Only SHA-1 Git repositories are supported in this beta.');
+  await branch(root); await head(root);
+  for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD']) {
+    if ((await git(root, ['rev-parse', '--verify', marker], { allowFailure: true })).code === 0) throw new Error(`Finish the Git operation first: ${marker}`);
+  }
+  if ((await names(root, ['ls-files', '-u', '-z'])).length) throw new Error('Resolve Git index conflicts first.');
+}

package/src/core/policy.js

@@ -0,0 +1,37 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { git, names, nul } from './git.js';
+import { MANAGED, safePath, present, hash, validatePath } from './files.js';
+
+export async function policy(root) {
+  const file = await safePath(root, '.aimpignore');
+  const content = await present(file) ? await fs.readFile(file) : Buffer.alloc(0);
+  if (content.length > 1024 * 1024) throw new Error('.aimpignore is too large.');
+  return { content, hash: hash(content) };
+}
+export async function included(paths, rules, { includeManaged = false } = {}) {
+  const candidates = [...new Set(paths)].filter(rel => { validatePath(rel); return includeManaged || !MANAGED.has(rel); });
+  if (!candidates.length || !rules.content.length) return candidates;
+  const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'aimp-policy-'));
+  try {
+    await git(temp, ['init', '--quiet']);
+    const excludes = path.join(temp, 'rules'); await fs.writeFile(excludes, rules.content, { mode: 0o600 });
+    const result = await git(temp, ['-c', `core.excludesFile=${excludes}`, 'check-ignore', '--no-index', '-z', '--stdin'], {
+      input: Buffer.from(candidates.map(p => `./${p}`).join('\0') + '\0'), allowFailure: true,
+      env: { GIT_LITERAL_PATHSPECS: '0' },
+    });
+    if (![0, 1].includes(result.code)) throw new Error(`Invalid ignore policy: ${result.stderr}`);
+    const ignored = new Set(nul(result.stdout).map(p => p.replace(/^\.\//, '')));
+    return candidates.filter(rel => !ignored.has(rel));
+  } finally { await fs.rm(temp, { recursive: true, force: true }); }
+}
+export async function projectFiles(root, rules) {
+  return included(await names(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']), rules);
+}
+export async function guardAttributes(root, paths) {
+  if (!paths.length) return;
+  const result = await git(root, ['check-attr', '-z', '--stdin', 'filter', 'working-tree-encoding'], { input: Buffer.from(paths.join('\0') + '\0') });
+  const values = nul(result.stdout);
+  for (let i = 0; i < values.length; i += 3) if (!['unspecified', 'unset'].includes(values[i + 2])) throw new Error(`Unsupported Git attribute ${values[i + 1]}: ${JSON.stringify(values[i])}`);
+}

package/src/core/projects.js

@@ -0,0 +1,114 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { git, branch, head, status } from './git.js';
+import { mirrorTarget, present, copy, fingerprint, equal, safePath, atomicJson } from './files.js';
+import { stateRoot, saveState, saveJournal, clearJournal, findMirror } from './state.js';
+import { policy, projectFiles, guardAttributes } from './policy.js';
+import { changes, createCheckpoint, writeMetadata, validateRepository } from './engine.js';
+
+export async function initialize(root, state, target, { confirm, replacing = false, signal } = {}) {
+  await validateRepository(root);
+  if ((await status(root)).length) throw new Error('Original must be clean before initialization.');
+  const name = await branch(root), originalHead = await head(root);
+  target = await mirrorTarget(root, target, stateRoot());
+  const owner = await findMirror(target);
+  if (owner && owner !== root) throw new Error('Target belongs to another original project.');
+  if (await present(target)) {
+    if (!(await fs.stat(target)).isDirectory()) throw new Error('Mirror target is not a directory.');
+    if ((await fs.readdir(target)).length && !replacing) throw new Error('Target is not empty. Use /reinit to review replacement.');
+  }
+  // A shared mirror is relocated as a unit, preserving other branches.
+  const existing = Object.values(state.pairs)[0];
+  if (existing && existing.mirror !== target && !replacing) target = existing.mirror;
+  if (existing) {
+    await validateRepository(existing.mirror);
+    const active = state.pairs[await branch(existing.mirror)];
+    if (!active || (await changes(existing.mirror, active, await policy(root))).changes.length) throw new Error('Active mirror branch has pending work. Sync or serialize it before initialization.');
+  }
+  const rules = await policy(root), files = await projectFiles(root, rules);
+  await guardAttributes(root, files);
+  const id = crypto.randomUUID(), stage = `${target}.aimp-stage-${id}`, payload = path.join(stateRoot(), 'initializations', id);
+  await fs.mkdir(path.join(payload, 'payload'), { recursive: true, mode: 0o700 });
+  await fs.mkdir(path.dirname(stage), { recursive: true });
+  await fs.mkdir(stage, { recursive: false });
+  let journaled = false;
+  try {
+    const entries = [];
+    for (const rel of files) {
+      if (signal?.aborted) throw new Error('Cancelled.');
+      const after = await fingerprint(root, rel);
+      if (!after) continue;
+      await copy(root, rel, payload, `payload/${entries.length}`, after.mode);
+      await copy(root, rel, stage, rel, after.mode);
+      entries.push({ path: rel, after });
+    }
+    await git(stage, ['init', '--quiet', '--initial-branch', name]);
+    await git(stage, ['config', 'user.name', 'aimp']); await git(stage, ['config', 'user.email', 'aimp@local.invalid']);
+    const commit = await createCheckpoint(stage, null, entries, payload, `chore(aimp): initialize ${name}`);
+    await git(stage, ['update-ref', `refs/heads/${name}`, commit]); await git(stage, ['read-tree', commit]);
+    const pair = { branch: name, mirror: target, baselineAi: commit, baselineOriginal: originalHead,
+      policyHash: rules.hash, batch: crypto.randomUUID(), acknowledgements: {}, applied: {} };
+    await writeMetadata(stage, state.projectId, pair);
+    await fs.writeFile(path.join(stage, '.git/info/exclude'), '/AIMP_REPORT.md\n/AGENTS-AIMP.md\n/.aimpignore\n');
+    if (rules.content.length) await fs.writeFile(path.join(stage, '.aimpignore'), rules.content);
+    if (existing && !replacing) {
+      // Transfer only the freshly created mirror commit, never original Git history.
+      if ((await git(existing.mirror, ['show-ref', '--verify', `refs/heads/${name}`], { allowFailure: true })).code === 0) throw new Error('Mirror branch already exists. Use /use.');
+      await git(existing.mirror, ['fetch', '--quiet', '--no-tags', stage, `refs/heads/${name}`]);
+      await git(existing.mirror, ['switch', '-c', name, 'FETCH_HEAD']);
+      pair.mirror = existing.mirror;
+      await writeMetadata(existing.mirror, state.projectId, pair);
+      state.pairs[name] = pair; await saveState(root, state); return pair;
+    }
+    if (existing && replacing) {
+      // Retain all old branch histories in the replacement; only the active branch is rebuilt.
+      for (const other of Object.keys(state.pairs).filter(b => b !== name)) {
+        await git(stage, ['fetch', '--quiet', '--no-tags', existing.mirror, `refs/heads/${other}:refs/heads/${other}`]);
+      }
+    }
+    if (await head(root) !== originalHead || (await policy(root)).hash !== rules.hash) throw new Error('Original changed during initialization.');
+    for (const e of entries) if (!equal(await fingerprint(root, e.path), e.after)) throw new Error('Original file changed during initialization.');
+    const occupied = await present(target) && (await fs.readdir(target)).length > 0;
+    if (occupied && !await confirm(`Replace ${target}? Its current contents will be retained in a backup folder.`)) return null;
+    if (signal?.aborted) throw new Error('Cancelled.');
+    const backup = `${target}.aimp-backup-${id}`;
+    const next = structuredClone(state);
+    for (const p of Object.values(next.pairs)) p.mirror = target;
+    next.pairs[name] = pair;
+    const tx = { version: 3, kind: 'initialize', id, root, target, stagePath: stage, backup, nextState: next };
+    await saveJournal(root, tx); journaled = true;
+    if (await present(target)) await fs.rename(target, backup);
+    await fs.rename(stage, target); await saveState(root, next); await clearJournal(root); journaled = false;
+    await atomicJson(path.join(payload, 'receipt.json'), { target, backup: occupied ? backup : null });
+    return { ...pair, backup: occupied ? backup : null };
+  } finally {
+    if (!journaled) { await fs.rm(stage, { recursive: true, force: true }); await fs.rm(path.join(payload, 'payload'), { recursive: true, force: true }); }
+  }
+}
+export async function recoverInitialization(root, tx) {
+  if (tx.root !== root || tx.kind !== 'initialize') throw new Error('Invalid initialization journal.');
+  await mirrorTarget(root, tx.target, stateRoot());
+  if (!/^[a-f0-9-]{36}$/.test(tx.id) || tx.stagePath !== `${tx.target}.aimp-stage-${tx.id}` || tx.backup !== `${tx.target}.aimp-backup-${tx.id}`) throw new Error('Invalid initialization recovery paths.');
+  if (await present(tx.stagePath)) {
+    if (await present(tx.target)) {
+      if (await present(tx.backup)) throw new Error('Both destination and backup exist; review reinit recovery manually.');
+      await fs.rename(tx.target, tx.backup);
+    }
+    await fs.rename(tx.stagePath, tx.target);
+  }
+  await validateRepository(tx.target);
+  await saveState(root, tx.nextState); await clearJournal(root);
+}
+export async function useBranch(root, state) {
+  const name = await branch(root), pair = state.pairs[name];
+  if (!pair) throw new Error('Branch is not initialized. Run /init.');
+  await validateRepository(pair.mirror);
+  const active = state.pairs[await branch(pair.mirror)];
+  if (!active) throw new Error('Unregistered mirror branch.');
+  if ((await changes(pair.mirror, active, await policy(root))).changes.length) throw new Error('Mirror has pending changes, including commits. Finish that branch first.');
+  await git(pair.mirror, ['switch', name]);
+  await safePath(pair.mirror, 'AIMP_REPORT.md');
+  await writeMetadata(pair.mirror, state.projectId, pair);
+  return pair;
+}

package/src/core/state.js

@@ -0,0 +1,85 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { atomicJson, canonical, hash, present, syncDirectory } from './files.js';
+
+export const stateRoot = () => path.join(process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'aimp');
+export const projectId = root => hash(root).slice(0, 16);
+export const stateFile = root => path.join(stateRoot(), `${projectId(root)}.json`);
+export const journalFile = root => path.join(stateRoot(), `${projectId(root)}.transaction.json`);
+export async function readJson(file) { if (!await present(file)) return null; if ((await present(file)).isSymbolicLink()) throw new Error('Refusing linked state.'); return JSON.parse(await fs.readFile(file, 'utf8')); }
+export async function loadState(root) {
+  const state = await readJson(stateFile(root));
+  if (!state) return null;
+  if (![2, 3].includes(state.schemaVersion) || !state.pairs || !state.original || state.projectId !== projectId(root) || path.resolve(state.original) !== root) throw new Error('Invalid or unsupported AIMP state. Restore a state backup before continuing.');
+  for (const [name, pair] of Object.entries(state.pairs)) {
+    if (pair.branch !== name || typeof pair.mirror !== 'string' || !path.isAbsolute(pair.mirror) || !/^[a-f0-9]{40}$/.test(pair.baselineAi || '')) throw new Error('Invalid branch state.');
+  }
+  return state;
+}
+export const saveState = (root, state) => atomicJson(stateFile(root), state);
+export const loadJournal = root => readJson(journalFile(root));
+export const saveJournal = (root, tx) => atomicJson(journalFile(root), tx);
+export async function clearJournal(root) { await fs.rm(journalFile(root), { force: true }); await syncDirectory(stateRoot()); }
+export function newState(root) { return { schemaVersion: 3, projectId: projectId(root), original: root, language: 'en', pairs: {}, history: [] }; }
+export async function migrate(root, old) {
+  if (old.schemaVersion === 3) return old;
+  if (await loadJournal(root)) throw new Error('Legacy recovery journal exists. Preserve its backup; finish legacy recovery before migration.');
+  const backup = `${stateFile(root)}.v2-${Date.now()}.bak`;
+  await fs.copyFile(stateFile(root), backup); await fs.chmod(backup, 0o600);
+  const next = { ...old, schemaVersion: 3 };
+  next.pairs = Object.fromEntries(Object.entries(old.pairs).map(([name, pair]) => [name, {
+    branch: name, mirror: pair.mirror, baselineAi: pair.baselineAi, baselineOriginal: pair.baselineOriginal,
+    batch: pair.batch, policyHash: null, acknowledgements: {}, applied: {}, baselineNeedsReview: true,
+  }]));
+  await saveState(root, next);
+  return { state: next, backup };
+}
+async function processIdentity(pid) {
+  try { const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8'); return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]; }
+  catch { return null; }
+}
+async function alive(owner) {
+  if (!Number.isSafeInteger(owner?.pid) || owner.pid <= 0) return true;
+  try { process.kill(owner.pid, 0); } catch (e) { return e.code !== 'ESRCH'; }
+  const identity = await processIdentity(owner.pid);
+  return !owner.start || !identity || identity === owner.start;
+}
+export async function withLock(root, operation) {
+  await fs.mkdir(stateRoot(), { recursive: true, mode: 0o700 });
+  if (await canonical(stateRoot()) !== path.resolve(stateRoot())) throw new Error('State directory must not contain symlinks.');
+  const lock = path.join(stateRoot(), `${projectId(root)}.lock`), token = crypto.randomUUID();
+  async function acquire() {
+    try { await fs.mkdir(lock); }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const reap = `${lock}.reap`;
+      try { await fs.mkdir(reap); } catch { throw new Error('Project is locked by another AIMP process.'); }
+      try {
+        let owner;
+        try { owner = await readJson(path.join(lock, 'owner.json')); } catch { /* Unknown owner is never stolen. */ }
+        if (!owner || await alive(owner)) throw new Error('Project is locked by another AIMP process.', { cause: e });
+        await fs.rm(lock, { recursive: true });
+        await fs.mkdir(lock);
+      } finally { await fs.rmdir(reap); }
+    }
+    await atomicJson(path.join(lock, 'owner.json'), { pid: process.pid, start: await processIdentity(process.pid), token });
+  }
+  await acquire();
+  try { return await operation(); }
+  finally {
+    const owner = await readJson(path.join(lock, 'owner.json'));
+    if (owner?.token === token) await fs.rm(lock, { recursive: true });
+  }
+}
+export async function findMirror(root) {
+  let entries; try { entries = await fs.readdir(stateRoot()); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  const matches = [];
+  for (const name of entries.filter(n => /^[a-f0-9]{16}\.json$/.test(n))) {
+    const state = await readJson(path.join(stateRoot(), name));
+    for (const pair of Object.values(state?.pairs || {})) if (path.resolve(pair.mirror) === root) matches.push({ original: state.original, pair });
+  }
+  if (new Set(matches.map(m => m.original)).size > 1) throw new Error('Mirror belongs to multiple original projects. Resolve the registry first.');
+  return matches[0]?.original || null;
+}

package/src/ui-utils.js

@@ -0,0 +1,38 @@
+// The viewport counts terminal cells, not source lines. ANSI input is escaped by the CLI.
+export function cellWidth(character) {
+  if (/\p{Mark}/u.test(character)) return 0;
+  const cp = character.codePointAt(0);
+  return cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7af || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x1f300) ? 2 : 1;
+}
+export function wrapRows(lines, width) {
+  const rows = [];
+  for (const source of lines) {
+    let row = '', cells = 0;
+    for (const character of source.replace(/\t/g, '    ')) {
+      const size = cellWidth(character);
+      if (cells + size > width && row) { rows.push(row); row = ''; cells = 0; }
+      row += character; cells += size;
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+export function decodeMouse(scroll) {
+  let pending = Buffer.alloc(0);
+  return { push(chunk) {
+    pending = Buffer.concat([pending, chunk]); const output = [];
+    while (pending.length) {
+      if (pending[0] !== 27) { output.push(pending.subarray(0, 1)); pending = pending.subarray(1); continue; }
+      if (pending.length < 3 && Buffer.from('\x1b[<').subarray(0, pending.length).equals(pending)) break;
+      if (pending.subarray(0, 3).toString() !== '\x1b[<') { output.push(pending.subarray(0, 1)); pending = pending.subarray(1); continue; }
+      const match = pending.toString().match(/^\x1b\[<(\d+);\d+;\d+([mM])/);
+      if (!match) {
+        if (pending.length <= 40 && /^\x1b\[<[\d;]*$/.test(pending.toString())) break;
+        pending = pending.subarray(3); continue;
+      }
+      if (match[2] === 'M' && (match[1] === '64' || match[1] === '65')) scroll(match[1] === '64' ? 3 : -3);
+      pending = pending.subarray(Buffer.byteLength(match[0]));
+    }
+    return Buffer.concat(output);
+  } };
+}

package/src/ui.js

@@ -0,0 +1,119 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text, render, useApp, useInput, useStdout } from 'ink';
+import { PassThrough } from 'node:stream';
+import { stdin, stdout } from 'node:process';
+import { createSession, loadState, pathCompleter, localized, safeText } from './cli.js';
+import { branch } from './core/git.js';
+import { wrapRows, decodeMouse } from './ui-utils.js';
+const h = React.createElement;
+
+function App({ ctx, profile, onScroll, controller }) {
+  const { exit } = useApp(), { stdout: screen } = useStdout();
+  const [size, setSize] = useState({ columns: screen.columns || 80, rows: screen.rows || 24 });
+  const [language, setLanguage] = useState('en'), [activeBranch, setActiveBranch] = useState('…');
+  const [value, setValue] = useState(''), [logs, setLogs] = useState([]), [offset, setOffset] = useState(0);
+  const [pending, setPending] = useState(null), [busy, setBusy] = useState(false), [monitor, setMonitor] = useState(null);
+  const busyRef = useRef(false), pendingRef = useRef(null), completion = useRef(null), quitting = useRef(false);
+  const t = (en, id) => localized(language, en, id);
+  const log = message => { setLogs(old => [...old, ...safeText(message).split('\n')].slice(-5000)); setOffset(0); };
+  const session = useMemo(() => createSession(ctx, {
+    profile, signal: controller.signal, output: log,
+    prompt: (message, options) => new Promise((resolve, reject) => {
+      const abort = () => { pendingRef.current = null; setPending(null); reject(new Error('Cancelled.')); };
+      const request = { message, kind: options.kind, resolve: v => { controller.signal.removeEventListener('abort', abort); resolve(v); } };
+      pendingRef.current = request; setPending(request); controller.signal.addEventListener('abort', abort, { once: true });
+    }),
+  }), [ctx, profile, controller]);
+  useEffect(() => {
+    const resize = () => setSize({ columns: screen.columns || 80, rows: screen.rows || 24 });
+    screen.on('resize', resize);
+    Promise.all([loadState(ctx.original), branch(ctx.root)]).then(([state, name]) => { setLanguage(state?.language || 'en'); setActiveBranch(name); }).catch(e => log(e.message));
+    return () => screen.off('resize', resize);
+  }, [ctx, screen]);
+  const rows = Math.max(6, size.rows - 1), width = Math.max(16, size.columns - 2), small = rows < 22;
+  const showMonitor = Boolean(monitor && width >= 100 && rows >= 18);
+  const leftWidth = showMonitor ? Math.floor(width * 0.65) : width;
+  const textWidth = Math.max(10, leftWidth - 2);
+  const candidates = !pending && value.startsWith('/') ? session.commands.filter(c => c.startsWith(value)) : [];
+  const headerRows = small ? 3 : 7;
+  const promptLabel = pending ? pending.message : ctx.mode === 'mirror' ? '$ aimp-ai> ' : '$ aimp> ';
+  const inputRows = wrapRows([`${promptLabel}${value}▏`], textWidth).slice(-Math.min(4, Math.max(1, rows - headerRows - 4)));
+  const suggestionRows = candidates.length ? wrapRows([candidates.join('  ')], textWidth).slice(0, 2) : [];
+  const chatHeight = Math.max(1, rows - headerRows - inputRows.length - suggestionRows.length - 3);
+  const wrappedLogs = wrapRows(logs, textWidth), maxOffset = Math.max(0, wrappedLogs.length - chatHeight), scroll = Math.min(offset, maxOffset);
+  const visible = wrappedLogs.slice(Math.max(0, wrappedLogs.length - scroll - chatHeight), wrappedLogs.length - scroll);
+  useEffect(() => { onScroll.current = amount => setOffset(old => Math.max(0, Math.min(maxOffset, old + amount))); return () => { onScroll.current = null; }; }, [maxOffset, onScroll]);
+  async function submit() {
+    const answer = value; setValue(''); completion.current = null;
+    if (pendingRef.current) { const p = pendingRef.current; pendingRef.current = null; setPending(null); p.resolve(answer); return; }
+    if (busyRef.current || !answer.trim()) return;
+    busyRef.current = true; setBusy(true); setMonitor(null); log(`$ ${answer}`);
+    try {
+      const result = await session.execute(answer);
+      if (result.exit) return exit();
+      if (result.monitor) { setMonitor(result.monitor); setActiveBranch(result.monitor.branch); }
+      const state = await loadState(ctx.original); setLanguage(state?.language || 'en');
+    } catch (error) { log(`Error: ${error.message}`); }
+    finally { busyRef.current = false; setBusy(false); if (quitting.current) exit(); }
+  }
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      quitting.current = true; controller.abort();
+      if (!busyRef.current) exit();
+      return;
+    }
+    if (key.up || key.pageUp || key.home) return setOffset(old => key.home ? maxOffset : Math.min(maxOffset, old + (key.pageUp ? chatHeight : 1)));
+    if (key.down || key.pageDown || key.end) return setOffset(old => key.end ? 0 : Math.max(0, old - (key.pageDown ? chatHeight : 1)));
+    if (busyRef.current && !pendingRef.current) return;
+    if (key.return) { void submit(); return; }
+    if (key.tab) {
+      if (pending && pending.kind !== 'path') return;
+      if (completion.current) {
+        const cycle = completion.current; cycle.index = (cycle.index + (key.shift ? -1 : 1) + cycle.matches.length) % cycle.matches.length;
+        setValue(cycle.matches[cycle.index]); return;
+      }
+      const typed = value;
+      const resolve = matches => { if (!matches.length) return; completion.current = { matches, index: 0 }; setValue(matches[0]); };
+      if (pending) void pathCompleter(typed).then(([matches]) => resolve(matches)); else resolve(candidates);
+      return;
+    }
+    completion.current = null;
+    if (key.backspace || key.delete) { setValue(old => Array.from(old).slice(0, -1).join('')); return; }
+    if (!key.ctrl && !key.meta && !key.escape && input) setValue(old => old + input.replace(/[\x00-\x1f\x7f]/g, ''));
+  });
+  const logo = small ? ['╭─ AIMP ─╮'] : ['╭────────────────────╮', '│ A I M P            │', '│ AI MIRROR PROJECT  │', '╰────────────────────╯'];
+  const header = [...logo, `${ctx.mode === 'mirror' ? 'AI MIRROR' : 'ORIGINAL'} · ${activeBranch}`, ctx.root];
+  const left = h(Box, { width: leftWidth, flexDirection: 'column', height: rows },
+    ...header.slice(0, headerRows - 1).map((line, i) => h(Text, { key: `h${i}`, color: i < logo.length ? 'green' : undefined, wrap: 'truncate-end' }, safeText(line))),
+    h(Text, { dimColor: true, wrap: 'truncate-end' }, pending ? t('Waiting for input', 'Menunggu input') : busy ? t('Processing… Ctrl+C stops safely', 'Memproses… Ctrl+C berhenti aman') : t('Ready · Ctrl+C exit', 'Siap · Ctrl+C keluar')),
+    h(Box, { flexDirection: 'column', height: chatHeight, overflow: 'hidden' }, ...visible.map((line, i) => h(Text, { key: i }, line))),
+    h(Text, { dimColor: true, wrap: 'truncate-end' }, `↑↓ PgUp/PgDn Home/End · ${scroll ? `↑ ${scroll}` : t('latest', 'terbaru')}`),
+    ...suggestionRows.map((line, i) => h(Text, { key: `s${i}`, color: 'yellow' }, line)),
+    h(Text, { dimColor: true, wrap: 'truncate-end' }, t('Type / · Tab/Shift+Tab selects commands or paths', 'Ketik / · Tab/Shift+Tab pilih command atau path')),
+    ...inputRows.map((line, i) => h(Text, { key: `p${i}`, color: 'green' }, safeText(line)))
+  );
+  const right = showMonitor ? h(Box, { width: width - leftWidth, flexDirection: 'column', borderStyle: 'round', height: Math.min(rows, 18), paddingX: 1 },
+    h(Text, { color: 'blue' }, '$ status --snapshot'),
+    ...wrapRows([monitor.state, `Original dirty: ${monitor.originalDirty}`, `AI pending: ${monitor.aiPending}`, `Branch: ${monitor.mirrorBranch}`, `Path: ${monitor.mirror}`, ...monitor.files], width - leftWidth - 4).slice(0, 14).map((line, i) => h(Text, { key: i }, safeText(line)))
+  ) : null;
+  return h(Box, { flexDirection: 'row', height: rows, width }, left, right);
+}
+
+export async function runInk({ ctx, profile }) {
+  const controller = new AbortController(), scroll = { current: null }, filtered = new PassThrough();
+  filtered.isTTY = stdin.isTTY; filtered.setRawMode = enabled => stdin.setRawMode(enabled);
+  filtered.ref = () => stdin.ref(); filtered.unref = () => stdin.unref();
+  const decoder = decodeMouse(direction => scroll.current?.(direction));
+  const onData = chunk => { const cleaned = decoder.push(chunk); if (cleaned.length) filtered.write(cleaned); };
+  const stop = () => controller.abort();
+  stdin.on('data', onData); process.on('SIGTERM', stop);
+  stdout.write('\x1b[?1049h\x1b[?1000h\x1b[?1006h\x1b[2J\x1b[H');
+  try {
+    const app = render(h(App, { ctx, profile, controller, onScroll: scroll }), { stdin: filtered, stdout, exitOnCtrlC: false, patchConsole: false });
+    await app.waitUntilExit();
+  } finally {
+    controller.abort(); stdin.off('data', onData); process.off('SIGTERM', stop); filtered.destroy();
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdout.write('\x1b[?1006l\x1b[?1000l\x1b[?1049l');
+  }
+}