@hasna/todos 0.15.52 → 0.17.0

package/docs/native-storage.md

@@ -0,0 +1,405 @@
+# Native Storage Boundary
+
+`@hasna/todos` stays local-first where it is a local product. `todos-serve`, the
+native storage tooling, and the plan-artifact files run on local SQLite and
+local artifact files without network access, hosted credentials, SaaS accounts,
+or a shared cloud runtime package.
+
+The MCP server and the CLI are NOT wholly local. Their plan and task-list
+command families — and the CLI's stateful template commands — are served by the
+authenticated shared API, and the MCP tools that still read the on-box store are
+served only under the explicit local opt-in (`HASNA_TODOS_LOCAL=1`) — see "MCP
+tools and the on-box store" below. The plan-artifact surface is the local half
+of a shared record: the Markdown companion file is local, the plan it describes
+is not.
+
+The CLI's client transport is NOT implicitly local. Since the fleet fail-closed
+ruling (2026-09-04, hasna/apps#1613), a CLI run with neither API variable
+present exits non-zero with an error naming `HASNA_TODOS_API_URL` and
+`HASNA_TODOS_API_KEY` — it never silently serves the on-box SQLite store.
+Serving local SQLite through the CLI requires the explicit opt-in
+`HASNA_TODOS_LOCAL=1` (alias `TODOS_LOCAL=1`), which is how local-only CLI
+deployments, self-hosters, and tests opt in deliberately.
+
+Remote storage is explicit and repo-native. Internal Hasna deployments and
+future SaaS wrappers should configure it through `HASNA_TODOS_*` variables and
+provide the matching Postgres/S3 clients through the public `./storage` package
+export.
+
+## The data-backend switch
+
+There is no deployment-mode axis. One switch selects where data lives, with
+exactly two arms on each side of the HTTP boundary:
+
+- **Client (CLI/MCP/TUI)** — `sqlite` (the on-box file, reachable only under
+  the explicit local opt-in `HASNA_TODOS_LOCAL=1` / `TODOS_LOCAL=1`) or `http`
+  (the authenticated Todos `/v1` authority). The client never opens Postgres
+  directly.
+- **Server (`todos-serve`) / native storage tooling** — `sqlite` (no database
+  URL configured) or `postgres` (a `HASNA_TODOS_DATABASE_URL` is present).
+
+`HASNA_TODOS_API_URL` + `HASNA_TODOS_API_KEY` select the authenticated HTTP
+authority (client). `HASNA_TODOS_DATABASE_URL` selects the Postgres backend
+(server/native storage tooling). The storage-mode variables
+(`HASNA_TODOS_STORAGE_MODE` and their aliases) are RETIRED: their mere presence
+is a hard error (owner directive 2026-08-15), and no deployment-mode token is
+accepted. No third arm exists.
+
+Legacy hosted API toggles are not storage selectors. They cannot select the
+local store and cannot rescue a run that lacks both the API pair and the local
+opt-in.
+
+## CLI Remote HTTP Authority
+
+The open CLI remote route uses only these canonical settings:
+
+| Setting | Purpose |
+| --- | --- |
+| `HASNA_TODOS_API_URL` | Todos authority root, the same root ending in `/v1`, or the fleet gateway form `https://api.hasna.com/todos[/v1]`. |
+| `HASNA_TODOS_API_KEY` | API key supplied to the authority as a bearer credential. |
+
+Both must be set to select the HTTP authority. URL set without KEY (or KEY set
+without URL) is a hard error naming the missing variable — the CLI never falls
+back to the on-box SQLite store from a partial cloud configuration. With
+NEITHER set, the CLI fails closed (non-zero exit, error naming both variables
+and the opt-in) unless `HASNA_TODOS_LOCAL=1` (alias `TODOS_LOCAL=1`) explicitly
+opts into local SQLite mode. There is no default local mode and no
+`todos-local-fallback` notice path: a false-green rc 0 against the on-box store
+is impossible (the incident 715712 response was tightened by the ruling).
+
+The URL must use HTTPS, except for loopback development authorities. Userinfo,
+query strings, fragments, redirects, `/api/v1`, and other non-`<app>[//v1]`
+paths are rejected. The gateway form `https://api.hasna.com/<app>` is accepted
+and `/v1` is appended (the gateway strips the `<app>` segment and forwards to
+the `https://<app>.hasna.xyz` origin); `<app>/v1` is used verbatim. The CLI
+does not infer an authority from `TODOS_URL`, does not use a private SaaS
+route, and does not send the bearer credential across redirects.
+
+Remote selection is fail-closed. A missing URL or key, conflicting mode
+selectors, an incompatible collection route, authentication failure, timeout,
+or server failure is reported with a `REMOTE_*` diagnostic before local SQLite
+can open. A resource-level 404 remains a normal not-found result. There is no
+SQLite or Postgres fallback for a remote CLI invocation.
+
+The supported coordination surface includes storage/status diagnostics,
+projects, task lists, project-scoped plans, task create/upsert/list/show/update,
+task-list and plan moves, comments, start/complete/delete, and next/claim. A
+command without a safe `/v1` equivalent exits with `REMOTE_COMMAND_UNSUPPORTED`
+before local helpers run.
+
+`todos storage status --json` is a configuration-only diagnostic. On the http
+transport it reports the redacted `/v1` base, URL/key presence, HTTP transport, and
+the disabled local fallback without opening a database or making a network
+request. `todos health` and `todos doctor` authenticate against the required
+remote routes.
+
+`todos doctor` additionally audits REFERENTIAL INTEGRITY against the authority
+and its exit code is a verdict, not a "the call succeeded" flag: `0` clean, `1`
+findings (orphaned or dangling project / task-list references), `2` incomplete
+(a condition could not be measured, so health was not established). It prefers
+the server-side aggregate `GET /v1/integrity`, which the storage adapter computes
+with one SQL COUNT per condition on Postgres and SQLite alike; an authority that
+does not expose it leaves the task-level conditions `NOT CHECKED` unless
+`--scan-tasks` completes a read-only paged walk of `/v1/tasks`. Findings are
+report-only — `doctor --apply` remains refused outright in remote mode and never
+repairs an integrity finding in any mode.
+
+## Native AWS Configuration
+
+- `HASNA_TODOS_DATABASE_URL`: Postgres connection string for RDS-backed task
+  state.
+- `HASNA_TODOS_DATABASE_SSL`: boolean, defaults to `true`.
+- `HASNA_TODOS_DATABASE_SCHEMA`: optional schema name for service-owned
+  isolation.
+- `HASNA_TODOS_S3_BUCKET`: optional artifact bucket.
+- `HASNA_TODOS_S3_PREFIX`: object prefix, defaults to `todos/`.
+- `HASNA_TODOS_AWS_REGION`: AWS region for S3 and RDS-adjacent operations.
+- `HASNA_TODOS_S3_ENDPOINT`: optional endpoint for tests or compatible object
+  stores.
+- `HASNA_TODOS_S3_FORCE_PATH_STYLE`: boolean for local S3-compatible tests.
+- `HASNA_TODOS_SYNC_BATCH_SIZE`: positive integer, defaults to `500`.
+- `HASNA_TODOS_SYNC_DRY_RUN`: boolean sync preview flag.
+
+Plain local-development fallbacks are accepted with the same names minus the
+`HASNA_` prefix, for example `TODOS_DATABASE_URL`, and
+`TODOS_S3_BUCKET`. Public docs and wrappers should still prefer the canonical
+`HASNA_TODOS_*` names.
+
+Production secrets should follow a consistent namespaced convention, for
+example:
+
+- `<org>/<division>/<app>/<env>/env`
+- `<org>/<division>/<app>/<env>/rds`
+- `<org>/<division>/<app>/<env>/s3`
+
+Deployment-specific infrastructure identifiers — the managed Postgres cluster
+name and the secrets-manager path that holds the runtime database URL — are
+owned by the private hosting wrapper and supplied at runtime via the optional
+`HASNA_TODOS_RDS_CLUSTER` and `HASNA_TODOS_RDS_RUNTIME_PATH` environment
+variables; this open package ships no real cluster names or secrets-manager
+paths. Runtime wiring should set `HASNA_TODOS_DATABASE_URL` from the resolved
+secret. `TODOS_DATABASE_URL` is only a plain fallback for local development or
+wrappers that have not yet migrated.
+
+A SaaS wrapper owns tenant state, billing, accounts, deployment, observability,
+and production secret wiring. The open package owns local storage, the public
+storage contract, local tests, and explicit remote adapter interfaces.
+
+## Public Adapter Exports
+
+The public `@hasna/todos/storage` export now includes:
+
+- `loadTodosStorageConfig` and `createTodosStorageAdapter` for backend selection.
+- `STORAGE_TABLES`, `TODOS_STORAGE_ENV`, and `TODOS_STORAGE_FALLBACK_ENV` for
+  wrapper provenance and explicit env mapping.
+- `exportSqliteTodosStorageSnapshot` and `importSqliteTodosStorageSnapshot`
+  for local SQLite state movement without a hosted service.
+- `createHybridTodosStorageAdapter` for local SQLite CRUD with explicit
+  Postgres-backed remote snapshot push/pull.
+- `createPostgresTodosStorageAdapter` for pure remote CRUD backed by the same
+  Postgres JSONB sync records and a caller-provided query client.
+- `createPostgresTodosSyncStore` for RDS-backed snapshot push/pull and
+  cross-machine sync cursors through a caller-provided Postgres query client.
+- `createTodosS3ArtifactStore` for S3 object reads/writes/deletes through
+  signed `fetch` requests and caller-provided credentials.
+- `uploadRunArtifactsToS3` and `downloadRunArtifactsFromS3` for syncing
+  locally stored `task_run_artifacts` bytes to and from S3 while keeping the
+  local artifact metadata rows as the source of truth. Objects are
+  content-addressed under `artifacts/<task_id>/<sha256>` inside the configured
+  bucket prefix.
+- `uploadRunArtifactAtCreation` for the creation-time hop: when
+  `HASNA_TODOS_S3_BUCKET` (or the `TODOS_S3_BUCKET` fallback) is set, the CLI
+  `runs artifact` command, the MCP `add_task_run_artifact` tool, and the
+  environment-snapshot flows upload the stored bytes to S3 right after the
+  artifact row is created and record the remote reference on its metadata, so
+  `todos storage artifacts download` restores the bytes on any machine. The
+  hop is fail-soft: without a bucket or with missing credentials the artifact
+  stays local-only and creation never fails.
+
+These exports are dependency-light by design. The open package does not bundle
+platform billing, tenant tables, deployment code, or a cloud SDK. Internal
+deployments and wrappers can provide `pg` clients, credentials, and secret
+loading from their own runtime.
+
+## Plan Markdown Artifacts
+
+Plan records are served by the authenticated shared API; a project-scoped plan
+also has an optional local Markdown companion file that this CLI writes on this
+machine. The root is always chosen by the caller with
+`--artifact-root <directory>` — a real local project directory. A path returned
+by the API is never used. The companion lives at:
+
+```text
+<artifact-root>/.hasna/todos/plans/<project-id>/<plan-slug>--<id8>.md
+```
+
+The Markdown file is an offline-readable artifact for agents, reviews, handoffs,
+and branch work. It is not the registry: the shared plan record is the source of
+truth, and the file is a client-side copy.
+
+Each file uses the `hasna.todos.plan/v1` schema in frontmatter:
+
+```markdown
+---
+schema: "hasna.todos.plan/v1"
+plan_id: "<stable plan UUID>"
+plan_slug: "launch-plan"
+project_id: "<stable project UUID>"
+task_list_id: null
+agent_id: null
+stable_id: "<same stable plan UUID>"
+name: "Launch Plan"
+status: "active"
+created_at: "2026-06-30T00:00:00.000Z"
+updated_at: "2026-06-30T00:00:00.000Z"
+artifact_updated_at: "2026-06-30T00:00:00.000Z"
+---
+
+# Launch Plan
+
+## Tasks
+
+- [ ] Example task
+  <!-- todos: task_id=<task-id> status=pending priority=medium -->
+```
+
+The path resolver only accepts safe project and plan path segments and requires
+a project-scoped plan; an unscoped plan has no artifact because the layout is
+explicitly under `<project-id>`.
+
+`todos plans --show <id-or-slug> --artifact-root <directory>` reads the
+companion file when present and includes the parsed artifact metadata and body
+in JSON output. The text view prints the artifact path. If the file is missing,
+the command still shows the shared plan record.
+
+For backwards compatibility, artifact readers also check the legacy UUID path:
+
+```text
+<artifact-root>/.hasna/todos/plans/<project-id>/<plan-id>.md
+```
+
+When both files exist, the slugged `<plan-slug>--<id8>.md` artifact wins. A
+later `--write-artifacts` run materializes the slugged artifact while leaving
+legacy files untouched for operator review.
+
+For migration and diagnostics:
+
+```bash
+todos plans --write-artifacts --artifact-root <directory>
+todos plans --artifact <id-or-slug> --artifact-root <directory> --json
+```
+
+Before 0.16.0 the artifact root was implicit: the plan was read from local
+SQLite and its recorded project path supplied the root, so the form was
+`todos plans --artifact <id-or-slug> --json`. That invocation now exits
+non-zero with `--artifact-root is required`. The root is always the caller's
+choice, because a path returned by the shared API never authorizes client
+filesystem access.
+
+`--write-artifacts` materializes Markdown files for every project-scoped plan in
+the current project scope using readable slug filenames. `--artifact` reports
+the resolved file path, whether the file exists, parse errors, task references,
+and deterministic conflicts between the shared plan record and Markdown
+frontmatter/task comments. The CLI does not silently treat the Markdown file as
+authoritative when conflicts exist; agents should resolve the conflict through
+the CLI or an explicit migration task.
+
+## MCP tools and the on-box store
+
+The MCP server no longer opens the on-box SQLite store implicitly. `getDatabase()`
+throws `API_DATABASE_FALLBACK_FORBIDDEN` unless the call supplies an explicit
+path or the environment selects the local store
+(`selectsTodosLocalStore()` — the deliberate `HASNA_TODOS_LOCAL=1` /
+`TODOS_LOCAL=1` opt-in on an environment that configures no authority or
+credential of its own).
+
+Tools that read the store through the shared API or read no store at all are
+unaffected. Tools that still call into the local data layer directly answer with
+the typed `{"code":"API_DATABASE_FALLBACK_FORBIDDEN"}` payload on the default
+posture, whose `suggestion` names the opt-in; the server logs the same code. The
+ten plan/task-list tools (`create_plan`, `list_plans`, `get_plan`, `update_plan`,
+`delete_plan`, `create_task_list`, `list_task_lists`, `get_task_list`,
+`update_task_list`, `delete_task_list`) return the typed
+`REMOTE_API_CONFIG_MISSING` refusal that names the missing configuration.
+
+Measured at 0.16.0 with `TODOS_PROFILE=full` on the default (no-credential)
+posture (361 tools, 125 of them taking no required arguments), 68 of the 125
+returned `API_DATABASE_FALLBACK_FORBIDDEN`:
+
+- templates: `list_templates`, `init_templates` (the rest of the family —
+  `create_template`, `preview_template`, `export_template`, `import_template`,
+  `create_task_from_template` — takes arguments, so it is outside the
+  zero-argument census and reads the same store; `list_template_library` and
+  `write_template_library` are bundled-only and unaffected)
+- tags and labels: `list_tags`, `list_labels`
+- agent work: `get_org_chart`, `suggest_agent_name`, `get_usage_ledger`,
+  `get_leaderboard`, `list_agent_run_queue`, `run_next_agent_dispatch`,
+  `list_task_runs`, `finish_task_run`, `list_task_findings`
+- health and reporting: `run_doctor`, `todos_retro`, `todos_inbox`,
+  `build_local_report`, `get_planning_forecast`, `get_activity_timeline`,
+  `get_time_report`, `export_agent_reliability_scorecards`
+- stale, blocked and archived work: `get_stale_tasks`, `get_blocked_tasks`,
+  `get_blocking_tasks`, `get_critical_path`, `patrol_tasks`,
+  `archive_completed`, `get_archived_tasks`, `notify_upcoming_deadlines`,
+  `get_sla_breaches`, `rebalance_workload`
+- boards, calendar and review: `list_boards`, `list_calendar_events`,
+  `export_calendar_ics`, `get_review_queue`, `list_review_queue`
+- knowledge, risk and search: `list_knowledge_records`,
+  `export_knowledge_records`, `list_risks`, `export_risk_register`,
+  `list_retrospectives`, `create_retrospective`, `export_retrospectives`,
+  `sync_kg`, `find_duplicate_tasks`, `list_search_views`,
+  `query_tasks_by_fields`, `migrate_workflow_states`
+- files, locks and handoffs: `list_file_locks`, `list_handoffs`,
+  `get_latest_handoff`, `get_file_heat_map`, `list_active_files`,
+  `list_inbox_items`, `import_external_issues`
+- backups, integrity and fixtures: `create_local_backup`,
+  `check_local_integrity`, `poll_local_snapshots`, `import_onboarding_fixture`
+- focus and audit: `start_focus_session`, `list_focus_sessions`,
+  `get_idle_focus_prompts`, `get_audit_ledger`
+- projects, notifications and dispatch: `bootstrap_project`,
+  `check_local_notifications`, `list_dispatches`, `run_due_dispatches`,
+  `generate_release_notes`
+
+The shared-API MCP tools that need a credential — `list_tasks`, `list_projects`,
+`get_status`, `get_my_tasks`, `get_health`, `standup`, `list_agents`,
+`machines_*` — answer the typed `REMOTE_API_CONFIG_MISSING` on the default
+posture: the documented fail-closed behaviour rather than a lost local surface.
+Five more zero-argument tools refuse caller input or local state with the typed
+`INVALID_INPUT` / `ENCRYPTION_KEY_UNAVAILABLE` / `ENCRYPTED_PAYLOAD_INVALID`,
+and five answer a readable text refusal. Measured on the same 125-tool census, no
+zero-argument tool returns an opaque `UNKNOWN_ERROR` — neither on this default
+posture nor under the `HASNA_TODOS_LOCAL=1` opt-in below, where
+`create_retrospective` and `finish_task_run` now answer the typed
+`INVALID_INPUT` for their missing scope / run id instead of the opaque
+`UNKNOWN_ERROR` they returned earlier in 0.16.0.
+
+Run the MCP server with `HASNA_TODOS_LOCAL=1` to serve these tools from the
+on-box store. That opt-in is honoured only when the environment configures no
+authority or credential: with `HASNA_TODOS_API_KEY` or `HASNA_TODOS_API_URL`
+set, a configured environment outranks the opt-in and these tools are
+unreachable in 0.16.0. Converting them to the shared API is tracked separately;
+this document records the boundary rather than claiming the surface is
+converted.
+
+## Hybrid Sync Shape (explicit migration machinery)
+
+`createHybridTodosStorageAdapter` builds a local-plus-remote adapter when the
+caller passes a Postgres-style query client or sync store. It is migration/sync
+machinery invoked explicitly — it is NOT an arm of the data-backend switch, and
+no environment value selects it:
+
+- Local CRUD stays SQLite-backed and works offline.
+- `adapter.sync.exportSnapshot()` and `adapter.sync.importSnapshot()` move the
+  storage-level SQLite snapshot.
+- `adapter.remote.pushSnapshot()` writes the local snapshot into Postgres sync
+  records.
+- `adapter.remote.pullSnapshot()` reads Postgres sync records and imports them
+  into local SQLite.
+- `adapter.remote.syncOnce()` pulls first, then pushes the merged local
+  snapshot.
+
+This is the open-package boundary. SaaS tenant wrappers can be added on top
+without changing the local default or depending on a shared cloud package.
+
+## Postgres CRUD Shape
+
+A present `HASNA_TODOS_DATABASE_URL` builds a pure Postgres adapter when the
+caller passes a Postgres-style query client to
+`createTodosStorageAdapter`:
+
+- CRUD uses the repo-owned `todos_sync_records` JSONB table rather than SaaS
+  tenant tables.
+- The package does not import `pg`; wrappers or internal deployments provide
+  the connected client.
+- `createPostgresTodosStorageAdapter` is also exported directly for callers
+  that want to bypass backend selection.
+- Local SQLite remains the default unless `HASNA_TODOS_DATABASE_URL` is set
+  explicitly (with the one carve-out that a shadow mirror
+  `HASNA_TODOS_SHADOW=1` keeps SQLite as the source of truth).
+
+## S3 Artifact Sync
+
+Run artifacts recorded with local stored content can now be pushed to S3 through
+the public storage helpers:
+
+- `uploadRunArtifactsToS3({ store, db, filter })` verifies the local
+  content-addressed artifact bytes, uploads them using `createTodosS3ArtifactStore`,
+  and stores a `remote_artifact_store` reference on the `task_run_artifacts`
+  metadata row.
+- `downloadRunArtifactsFromS3({ store, db, filter })` reads that remote
+  reference, downloads the object, verifies the checksum, and restores the local
+  content-addressed file.
+
+The helper only needs a caller-provided S3 store. Credentials, secret loading,
+tenant scoping, and production scheduling remain outside the open package.
+
+The CLI exposes the same boundary:
+
+- `todos storage artifacts upload --run-id <id> --json` previews uploadable
+  local artifact bytes without network access.
+- `todos storage artifacts download --run-id <id> --json` previews remote
+  restore work without network access.
+- Add `--apply` to perform the S3 operation. Apply mode requires
+  `HASNA_TODOS_S3_BUCKET` plus `HASNA_TODOS_S3_ACCESS_KEY_ID` and
+  `HASNA_TODOS_S3_SECRET_ACCESS_KEY`; `HASNA_TODOS_S3_SESSION_TOKEN` is
+  optional.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/todos",
-  "version": "0.15.52",
+  "version": "0.17.0",
   "description": "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   "type": "module",
   "main": "dist/index.js",
@@ -53,37 +53,40 @@
     }
   },
   "workspaces": [
-    "dashboard",
     "ai"
   ],
   "files": [
     "dist",
-    "dashboard/dist",
     "postinstall.js",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/PLAN_API.md",
+    "docs/TASK_LIST_API.md",
+    "docs/TEMPLATE_API.md",
+    "docs/TASK_QUERY_API.md",
+    "docs/native-storage.md"
   ],
   "scripts": {
-    "build": "rm -rf dist dashboard/dist && cd dashboard && bun install --frozen-lockfile && bun run build && cd .. && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts src/project-registration.ts src/task-manifest.ts src/task-subtree-transfer.ts --outdir dist --root src --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && tsc --emitDeclarationOnly --outDir dist",
+    "build": "cd ai && bun install --frozen-lockfile && cd .. && rm -rf dist && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts src/project-registration.ts src/task-manifest.ts src/task-subtree-transfer.ts --outdir dist --root src --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && tsc --emitDeclarationOnly --outDir dist",
     "build:js": "rm -rf dist && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts src/project-registration.ts src/task-manifest.ts src/task-subtree-transfer.ts --outdir dist --root src --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && tsc --emitDeclarationOnly --outDir dist",
     "build:server": "rm -rf dist && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts src/project-registration.ts src/task-manifest.ts src/task-subtree-transfer.ts --outdir dist --target bun --external '@hasna/contracts' --external '@hasna/contracts/*'",
     "migrate": "bun run src/server/index.ts migrate",
     "backfill:comment-redaction": "bun run src/server/index.ts redact-comments",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
-    "build:dashboard": "cd dashboard && bun install --frozen-lockfile && bun run build",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
-    "test": "bun test",
-    "test:no-cloud": "bun test src/no-cloud-boundary.test.ts src/local-first.test.ts src/lib/public-release-gate.test.ts",
+    "test": "bun test --timeout 120000",
+    "test:no-cloud": "bun test --timeout 120000 src/no-cloud-boundary.test.ts src/local-first.test.ts src/lib/public-release-gate.test.ts",
     "dev:cli": "bun run src/cli/index.tsx",
     "dev:mcp": "bun run src/mcp/index.ts",
     "dev:serve": "bun run src/server/index.ts",
     "verify:release": "bun run scripts/verify-public-release.ts --mode=review",
     "verify:release-review": "bun run scripts/verify-npm-release-agent-review.ts",
     "verify:attested-container-candidate": "bun run scripts/attested-container-candidate.ts verify",
-    "test:attested-container-candidate": "bun test scripts/attested-container-candidate.test.ts",
+    "test:attested-container-candidate": "bun test --timeout 120000 scripts/attested-container-candidate.test.ts",
     "emit:iapp-deployment-compatibility-vector": "bun run scripts/attested-container-compatibility-vector.ts emit",
     "verify:iapp-deployment-compatibility-vector": "bun run scripts/attested-container-compatibility-vector.ts verify",
-    "test:attested-container-compatibility-vector": "bun test scripts/attested-container-compatibility-vector.test.ts",
+    "test:attested-container-compatibility-vector": "bun test --timeout 120000 scripts/attested-container-compatibility-vector.test.ts",
     "issue:release-review": "bun run scripts/issue-npm-release-agent-review.ts",
     "prepublishOnly": "bun run scripts/verify-public-release.ts --mode=publish",
     "postinstall": "node postinstall.js"
@@ -107,11 +110,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hasna/todos.git"
+    "url": "https://github.com/hasna/apps.git",
+    "directory": "apps/todos"
   },
-  "homepage": "https://github.com/hasna/todos",
+  "homepage": "https://github.com/hasna/apps/tree/main/apps/todos#readme",
   "bugs": {
-    "url": "https://github.com/hasna/todos/issues"
+    "url": "https://github.com/hasna/apps/issues"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -120,9 +124,8 @@
   "author": "Andrei Hasna <andrei@hasna.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@hasna/contracts": "0.14.2",
+    "@hasna/contracts": "1.0.2",
     "@hasna/events": "^0.1.11",
-    "@hasna/paths": "0.1.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",

package/postinstall.js

@@ -5,13 +5,64 @@
 // otherwise the legacy ~/.hasna/todos default. Failures are non-fatal: the
 // runtime creates the same directories on first use.
 import { existsSync, mkdirSync } from "node:fs";
+// --- Local path resolver -------------------------------------------------
+// @hasna/paths was deleted (hasna/apps#1535, 2026-09-03); this in-package
+// implementation preserves the resolver contract (XDG / macOS home layout
+// honoring HASNA_{CONFIG,DATA,STATE,CACHE}_HOME, with the same env-override
+// and home-override semantics the deleted package had).
+import { homedir as pathsResolverHomedir } from "node:os";
+import { join as pathsResolverJoin } from "node:path";
+
+const PATHS_RESOLVER_KIND_ENV = {
+  config: "HASNA_CONFIG_HOME",
+  data: "HASNA_DATA_HOME",
+  state: "HASNA_STATE_HOME",
+  cache: "HASNA_CACHE_HOME",
+};
+
+function pathsResolverBaseDir(kind, options) {
+  const env = options.env ?? process.env;
+  const override = env[PATHS_RESOLVER_KIND_ENV[kind]];
+  if (typeof override === "string" && override.length > 0) return override;
+  const home = options.home ?? pathsResolverHomedir();
+  const platform = options.platform ?? process.platform;
+  if (platform === "darwin") {
+    switch (kind) {
+      case "config":
+      case "data":
+        return pathsResolverJoin(home, "Library", "Application Support", "Hasna");
+      case "cache":
+        return pathsResolverJoin(home, "Library", "Caches", "Hasna");
+      case "state":
+        return pathsResolverJoin(home, "Library", "Logs", "Hasna");
+    }
+  }
+  switch (kind) {
+    case "config":
+      return pathsResolverJoin(home, ".config", "hasna");
+    case "data":
+      return pathsResolverJoin(home, ".local", "share", "hasna");
+    case "state":
+      return pathsResolverJoin(home, ".local", "state", "hasna");
+    case "cache":
+      return pathsResolverJoin(home, ".cache", "hasna");
+  }
+}
+
+function pathsResolverResolve(kind, options) {
+  const appSegment = options.internal === true ? pathsResolverJoin("internal", options.app) : options.app;
+  return pathsResolverJoin(pathsResolverBaseDir(kind, options), appSegment);
+}
+function dataDir(options) {
+  return pathsResolverResolve("data", options);
+}
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 const DATA_HOME_OVERRIDE = (process.env["HASNA_DATA_HOME"] || "").trim();
 
 try {
-  const { dataDir } = await import("@hasna/paths");
+  // (local resolver — @hasna/paths deleted, hasna/apps#1535)
   const resolved = dataDir({
     app: "todos",
     home: process.env["HOME"] || process.env["USERPROFILE"] || homedir(),