hanoman 0.1.46 → 0.1.50

package/docs/agent-integration.md

@@ -169,6 +169,10 @@ dan tak memakai agent token.
 | `POST /api/specs` | `backlog:write` | buat backlog item — bentuk payload di §7. |
 | `PATCH /api/specs/:id` | `backlog:write` | ubah item; konten hanya selagi belum dimulai. |
 | `POST /api/specs/:id/done` | `backlog:write` | tandai item **selesai** tanpa menjalankan sesi — untuk pekerjaan yang beres di luar hanoman. Body `{ reason?: string (≤280), confirm?: boolean }`, keduanya opsional; balasannya `Spec` yang sudah `stage:"done"`. Tak menjalankan maupun menghentikan sesi apa pun. |
+| `GET /api/specs/:id/attachments` | `backlog:read` | lampiran backlog item — gambar & dokumen yang dilampirkan manusia sebagai konteks kerja. |
+| `POST /api/specs/:id/attachments` | `backlog:write` | unggah lampiran (`multipart/form-data`, beberapa berkas per request). Berkas yang ditolak **tak** menggagalkan yang lain — periksa `rejected[]`. |
+| `GET /api/specs/:id/attachments/:attId` | `backlog:read` | byte satu lampiran. |
+| `DELETE /api/specs/:id/attachments/:attId` | `backlog:write` | hapus satu lampiran. |
 | `GET /api/specs/:id/docs` | `backlog:read` | dokumen yang ditulis sesi item itu. |
 | `GET /api/specs/:id/review` | `backlog:read` | diff hasil kerja sesi. |
 | `GET /api/projects/:id/docs` | `docs:read` | index Source of Truth project. |
@@ -299,6 +303,7 @@ memanggilnya; jangan lakukan tanpa manusia.
 | `branchFrom` yang tak ada di repo project → **400**, bukan diterima lalu gagal di tengah sesi | ambil kandidatnya dari `GET /api/projects/:id/branches` |
 | **401 telanjang** tak memisahkan "host salah" dari "token salah" dari "master switch mati" | probe `GET /api/health` sekali: 200 = host benar → masalahnya token atau master switch |
 | **403** bukan kegagalan permanen | bacalah field `need`, sampaikan ke manusia, minta capability itu ditambahkan |
+| **Lampiran backlog tak menyeberang sync** (`SpecAttachment` LOCAL-only, ADR-0124) | item yang sama di instance lain tampil **tanpa** lampiran. Kalau lampiran yang disebut manusia tak kamu temukan, kemungkinan besar kamu bicara ke instance yang bukan tempat lampiran itu diunggah — tanyakan, jangan simpulkan lampirannya tak ada |
 
 ## 10. Contoh alur end-to-end
 
@@ -461,6 +466,11 @@ dan seluruh `/api/vps*` (remote exec) **tidak ikut**, begitu pula merge/rebase (
 penghapusan backlog, dan perubahan `stage`. Batasan ini ada di katalog toolnya, bukan di token:
 token yang punya `sessions:write` sekalipun tak akan menemukan tool untuk memakainya. Lihat §8.
 
+**Lampiran backlog** (`/api/specs/:id/attachments*`, SPEC-843 · ADR-0124) juga sengaja **tak punya
+tool**: berkasnya lahir dari disk manusia, bukan dari model, dan tool MCP berbentuk JSON sehingga
+byte biner tak punya representasi di sana. REST-nya tetap terjangkau agent token
+ber-`backlog:read`/`backlog:write` — yang tak dipajang adalah **tool**-nya.
+
 ### Opsi
 
 | Variabel / flag | Arti |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanoman",
-  "version": "0.1.46",
+  "version": "0.1.50",
   "description": "Orchestrator + dashboard workflow docs-driven untuk sesi Claude Code / Codex",
   "type": "module",
   "repository": {

package/prisma/migrations/20260819120000_spec_attachment/migration.sql

@@ -0,0 +1,19 @@
+-- SPEC-843 · ADR-0124 · lampiran per backlog item.
+--
+-- Ditulis tangan (bukan `migrate dev`): worktree tetangga membuat `migrate dev` me-reset DB saat
+-- ada drift. ADITIF murni — satu tabel baru, tak ada tabel yang diredefinisi.
+--
+-- TANPA kolom `version`: entitas ini LOCAL-only dan tak pernah masuk changefeed sync.
+CREATE TABLE "SpecAttachment" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "specId" TEXT NOT NULL,
+    "projectId" TEXT NOT NULL,
+    "filename" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "SpecAttachment_specId_fkey" FOREIGN KEY ("specId") REFERENCES "Spec" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE INDEX "SpecAttachment_specId_idx" ON "SpecAttachment"("specId");

package/prisma/migrations/20260819130000_session_history_ended_reason/migration.sql

@@ -0,0 +1,27 @@
+-- SPEC-844 · ADR-0125 · riwayat sesi mencatat BAGAIMANA sebuah baris ditutup.
+--
+-- Ditulis tangan (bukan `migrate dev`): worktree tetangga membuat `migrate dev` me-reset DB saat
+-- ada drift. ADITIF murni — dua kolom NULLABLE tanpa default, tak ada tabel diredefinisi, jadi
+-- jebakan `ADD COLUMN … DEFAULT CURRENT_TIMESTAMP` (ADR-0090) tak berlaku di sini.
+ALTER TABLE "SessionHistory" ADD COLUMN "endedReason" TEXT;
+ALTER TABLE "SessionHistory" ADD COLUMN "reconciledAt" DATETIME;
+
+-- Backfill SEKALI JALAN. Baris lama tak bisa ditanyai, tapi jejaknya masih ada: `reconcileHistory`
+-- membaca `updatedAt` SEBELUM update-nya sendiri (jadi `updatedAt` melompat ke waktu boot dan
+-- meninggalkan `endedAt` di belakang), sementara `finishSession` menulis `endedAt = new Date()` DI
+-- DALAM update yang sama (jadi jaraknya nol). Terukur pada DB hidup 806 baris: tutup normal
+-- 0–39 ms (n=777) vs rekonsiliasi 275 966–82 224 277 ms (n=20) — empat orde besaran tanpa satu pun
+-- baris di antaranya; ambang 60 000 ms duduk di tengah celah itu.
+--
+-- Ini backfill, BUKAN aturan render: menjadikannya kontrak akan mengunci detail penyimpanan Prisma
+-- sebagai semantik produk. Prisma menyimpan DateTime SQLite sebagai INTEGER milidetik, jadi
+-- selisihnya aritmetika biasa; `CAST` dipasang supaya representasi lain (teks ISO) menghasilkan
+-- selisih 0 → nol baris cocok → seluruh tabel jatuh ke 'closed', yaitu perilaku sebelum spec ini.
+UPDATE "SessionHistory"
+   SET "endedReason" = 'reconciled', "reconciledAt" = "updatedAt"
+ WHERE "endedAt" IS NOT NULL
+   AND CAST("updatedAt" AS INTEGER) - CAST("endedAt" AS INTEGER) > 60000;
+
+UPDATE "SessionHistory"
+   SET "endedReason" = 'closed'
+ WHERE "endedAt" IS NOT NULL AND "endedReason" IS NULL;

package/prisma/schema.prisma

@@ -87,6 +87,30 @@ model Spec {
   sourceHistory Json?
   updatedAt  DateTime @updatedAt
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  attachments SpecAttachment[]
+}
+
+// SPEC-843 · ADR-0124 · lampiran per backlog item — konteks yang dipegang manusia saat memfilekan
+// item, dibaca agen di dalam sesi. Byte hidup di HANOMAN_UPLOAD_DIR (server-local, di luar repoDir);
+// `storageKey` opaque, `filename` nama asli tersanitasi untuk tampilan saja.
+//
+// LOCAL-only: TANPA `version`, jadi ia tak pernah masuk changefeed sync (cermin LeadFlow,
+// WebhookEndpoint, Changelog). Byte memang tak menyeberang (ADR-0062), dan metadata yang menyeberang
+// TANPA byte-nya hanya menghasilkan lampiran yang tak bisa dibuka di mesin lain — keadaan terburuk
+// dari ketiga pilihan. Sengaja BUKAN TicketAttachment: tiket dan backlog dua domain dengan aturan
+// sync dan tingkat kepercayaan yang berbeda (ADR-0124 §1/§4).
+model SpecAttachment {
+  id         String   @id @default(cuid())
+  specId     String
+  projectId  String   // denormal — kuota & isolasi per project, cermin TicketAttachment
+  filename   String
+  mimeType   String
+  size       Int
+  storageKey String
+  createdAt  DateTime @default(now())
+  spec       Spec     @relation(fields: [specId], references: [id], onDelete: Cascade)
+
+  @@index([specId])
 }
 
 // SPEC-516 · ADR-0105 · changelog naratif per project yang sudah dibangkitkan.
@@ -368,6 +392,13 @@ model SessionHistory {
   startedAt       DateTime  @default(now())
   endedAt         DateTime?
   exitCode        Int?
+  // SPEC-844 · ADR-0125 · CARA baris ini ditutup: "closed" (killSession) atau "reconciled" (pane
+  // sudah lenyap saat boot — hasilnya tak diketahui). null = baris lahir sebelum kolom ini ada.
+  // Kelas hasil (selesai/gagal) sengaja TIDAK disimpan: ia turunan exitCode (sessionOutcome).
+  endedReason     String?
+  // Kapan boot menemukan panenya lenyap. `endedAt` baris rekonsiliasi adalah batas BAWAH
+  // ("terakhir diketahui hidup"); kolom ini batas atasnya.
+  reconciledAt    DateTime?
   transcriptKey   String?
   transcriptBytes Int?
   createdAt       DateTime  @default(now())