@mndrk/agx 2.0.38 → 2.0.39

package/cloud-runtime/standalone/mcp/dist/types.js

@@ -0,0 +1,74 @@
+export const STAGE_ORDER = [
+    "ideation",
+    "planning",
+    "coding",
+    "qa",
+    "acceptance",
+    "pr",
+    "pr_review",
+    "merge",
+    "done",
+];
+/**
+ * Resolves task configuration by merging task-level settings with stage-level defaults.
+ * Task settings take precedence.
+ */
+export function resolveTaskConfig(task, stageConfig) {
+    const provider = task.provider || stageConfig?.provider || "unspecified";
+    const model = task.model || stageConfig?.model || "unspecified";
+    const swarm = task.swarm ?? stageConfig?.swarm ?? false;
+    const swarm_models = task.swarm_models?.length ? task.swarm_models : (stageConfig?.swarm_models || []);
+    return {
+        provider,
+        model,
+        swarm,
+        swarm_models,
+    };
+}
+// Parse YAML frontmatter from markdown
+export function parseFrontmatter(markdown) {
+    const match = markdown.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: markdown };
+    }
+    const frontmatter = {};
+    const lines = match[1].split('\n');
+    for (const line of lines) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex > 0) {
+            const key = line.slice(0, colonIndex).trim();
+            const value = line.slice(colonIndex + 1).trim();
+            // Parse numbers and booleans
+            if (value === 'true')
+                frontmatter[key] = true;
+            else if (value === 'false')
+                frontmatter[key] = false;
+            else if (/^\d+$/.test(value))
+                frontmatter[key] = parseInt(value);
+            else
+                frontmatter[key] = value;
+        }
+    }
+    return { frontmatter, body: match[2] };
+}
+// Extract title from markdown (first H1)
+export function extractTitle(markdown) {
+    const { body } = parseFrontmatter(markdown);
+    const match = body.match(/^#\s+(.+)$/m);
+    return match ? match[1] : undefined;
+}
+// Build content from frontmatter and body
+export function buildContent(frontmatter, body) {
+    const frontmatterStr = Object.entries(frontmatter)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join("\n");
+    return `---\n${frontmatterStr}\n---\n${body}`;
+}
+// Get next SDLC stage
+export function getNextStage(currentStage) {
+    const index = STAGE_ORDER.indexOf(currentStage);
+    if (index === -1 || index >= STAGE_ORDER.length - 1)
+        return null;
+    return STAGE_ORDER[index + 1];
+}
+//# sourceMappingURL=types.js.map

package/cloud-runtime/standalone/node_modules/@img/{sharp-linux-x64 → sharp-darwin-arm64}/package.json

@@ -1,13 +1,13 @@
 {
-  "name": "@img/sharp-linux-x64",
+  "name": "@img/sharp-darwin-arm64",
   "version": "0.34.5",
-  "description": "Prebuilt sharp for use with Linux (glibc) x64",
+  "description": "Prebuilt sharp for use with macOS 64-bit ARM",
   "author": "Lovell Fuller <npm@lovell.info>",
   "homepage": "https://sharp.pixelplumbing.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovell/sharp.git",
-    "directory": "npm/linux-x64"
+    "directory": "npm/darwin-arm64"
   },
   "license": "Apache-2.0",
   "funding": {
@@ -15,7 +15,7 @@
   },
   "preferUnplugged": true,
   "optionalDependencies": {
-    "@img/sharp-libvips-linux-x64": "1.2.4"
+    "@img/sharp-libvips-darwin-arm64": "1.2.4"
   },
   "files": [
     "lib"
@@ -25,22 +25,16 @@
   },
   "type": "commonjs",
   "exports": {
-    "./sharp.node": "./lib/sharp-linux-x64.node",
+    "./sharp.node": "./lib/sharp-darwin-arm64.node",
     "./package": "./package.json"
   },
   "engines": {
     "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
   },
-  "config": {
-    "glibc": ">=2.26"
-  },
   "os": [
-    "linux"
-  ],
-  "libc": [
-    "glibc"
+    "darwin"
   ],
   "cpu": [
-    "x64"
+    "arm64"
   ]
 }

package/cloud-runtime/standalone/node_modules/@img/{sharp-libvips-linux-x64 → sharp-libvips-darwin-arm64}/README.md

@@ -1,6 +1,6 @@
-# `@img/sharp-libvips-linux-x64`
+# `@img/sharp-libvips-darwin-arm64`
 
-Prebuilt libvips and dependencies for use with sharp on Linux (glibc) x64.
+Prebuilt libvips and dependencies for use with sharp on macOS 64-bit ARM.
 
 ## Licensing
 

package/cloud-runtime/standalone/node_modules/@img/{sharp-libvips-linux-x64 → sharp-libvips-darwin-arm64}/lib/glib-2.0/include/glibconfig.h

@@ -63,15 +63,15 @@ typedef unsigned int guint32;
 
 #define G_HAVE_GINT64 1          /* deprecated, always true */
 
-typedef signed long gint64;
-typedef unsigned long guint64;
+G_GNUC_EXTENSION typedef signed long long gint64;
+G_GNUC_EXTENSION typedef unsigned long long guint64;
 
-#define G_GINT64_CONSTANT(val)	(val##L)
-#define G_GUINT64_CONSTANT(val)	(val##UL)
+#define G_GINT64_CONSTANT(val)	(G_GNUC_EXTENSION (val##LL))
+#define G_GUINT64_CONSTANT(val)	(G_GNUC_EXTENSION (val##ULL))
 
-#define G_GINT64_MODIFIER "l"
-#define G_GINT64_FORMAT "li"
-#define G_GUINT64_FORMAT "lu"
+#define G_GINT64_MODIFIER "ll"
+#define G_GINT64_FORMAT "lli"
+#define G_GUINT64_FORMAT "llu"
 
 
 #define GLIB_SIZEOF_VOID_P 8
@@ -121,7 +121,6 @@ typedef unsigned long guintptr;
 
 #define G_VA_COPY va_copy
 
-#define G_VA_COPY_AS_ARRAY 1
 
 #define G_HAVE_ISO_VARARGS 1
 
@@ -203,7 +202,7 @@ typedef int GPid;
 
 #define GLIB_SYSDEF_AF_UNIX 1
 #define GLIB_SYSDEF_AF_INET 2
-#define GLIB_SYSDEF_AF_INET6 10
+#define GLIB_SYSDEF_AF_INET6 30
 
 #define GLIB_SYSDEF_MSG_OOB 1
 #define GLIB_SYSDEF_MSG_PEEK 2

package/cloud-runtime/standalone/node_modules/@img/{sharp-libvips-linux-x64 → sharp-libvips-darwin-arm64}/package.json

@@ -1,13 +1,13 @@
 {
-  "name": "@img/sharp-libvips-linux-x64",
+  "name": "@img/sharp-libvips-darwin-arm64",
   "version": "1.2.4",
-  "description": "Prebuilt libvips and dependencies for use with sharp on Linux (glibc) x64",
+  "description": "Prebuilt libvips and dependencies for use with sharp on macOS 64-bit ARM",
   "author": "Lovell Fuller <npm@lovell.info>",
   "homepage": "https://sharp.pixelplumbing.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovell/sharp-libvips.git",
-    "directory": "npm/linux-x64"
+    "directory": "npm/darwin-arm64"
   },
   "license": "LGPL-3.0-or-later",
   "funding": {
@@ -27,16 +27,10 @@
     "./package": "./package.json",
     "./versions": "./versions.json"
   },
-  "config": {
-    "glibc": ">=2.26"
-  },
   "os": [
-    "linux"
-  ],
-  "libc": [
-    "glibc"
+    "darwin"
   ],
   "cpu": [
-    "x64"
+    "arm64"
   ]
 }

package/cloud-runtime/standalone/notes/comments-context-demo.md

@@ -0,0 +1,141 @@
+# Demo: Task Comments as Execution Context
+
+## What was built
+- Task comments are part of signed execution context.
+- `lib/task-context.ts` composes prompt context with a `COMMENTS` section and computes `comments_digest` (SHA-256 over ordered comments).
+- Signed payload producers re-compute digest and re-sign when comments change:
+  - `POST /api/tasks/[id]/comments`
+  - `DELETE /api/tasks/[id]/comments/[commentId]`
+  - `GET /api/tasks/[id]`
+  - `POST /api/queue` (pull)
+  - MCP `tasks.get` and `queue.pull`
+- Signature includes `comments_digest`, so stale signatures are invalid after comment mutations.
+
+## Acceptance status (2026-02-07)
+- E2E blocked in this sandbox by port restrictions (cannot bind localhost on `127.0.0.1:3100`).
+- Cloud sync blocked in this sandbox: `tsx` IPC socket bind blocked.
+- Rerun in an environment that allows localhost binds + IPC sockets and has DB credentials, then record results here.
+
+## Local setup (required for demo)
+1. Install dependencies:
+```bash
+npm install
+```
+2. Configure env:
+```bash
+cp .env.example .env.local
+# Fill in DB values for:
+# - NEXT_PUBLIC_DB_URL (or DB_URL)
+# - DB_SERVICE_ROLE_KEY
+```
+3. Run dev server:
+```bash
+npm run dev
+```
+Expected:
+- App available at `http://localhost:3000`.
+- Auth + task data load via DB.
+
+## Demo (UI)
+1. Start the app: `npm run dev`
+2. Open dashboard and select a task.
+3. Add a comment in `Comments`.
+4. Confirm it appears in timeline.
+5. Refresh and verify prompt/context now includes the comment.
+
+Expected:
+- `COMMENTS` section includes the new entry.
+- `comments_digest` changes after each comment mutation.
+- Returned `signature` matches the new digest.
+
+## Demo (API)
+1. Add comment:
+```bash
+curl -X POST "http://localhost:3000/api/tasks/<taskId>/comments" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <access_token>" \
+  -d '{"content":"Add context here"}'
+```
+2. Fetch task:
+```bash
+curl -X GET "http://localhost:3000/api/tasks/<taskId>" \
+  -H "Authorization: Bearer <access_token>"
+```
+3. Verify:
+- `comments_digest` present and updated.
+- `context.prompt` contains `COMMENTS`.
+- `signature` changes when digest changes.
+
+## Demo (Queue/MCP)
+1. Pull via queue (`POST /api/queue`) or MCP (`queue.pull`).
+2. Verify returned prompt includes `COMMENTS` and digest/signature fields.
+3. Add another comment and pull again; verify digest/signature roll forward.
+
+## E2E (Playwright) — rerun commands
+```bash
+npm run test:e2e:sandbox -- e2e/comments.spec.ts
+```
+If you are not in a sandbox and want to override host/port:
+```bash
+SANDBOX=1 CLOUD_SYNC_DISABLED=1 E2E_HOST=0.0.0.0 E2E_PORT=3101 npx playwright test e2e/comments.spec.ts
+```
+Expected:
+- Playwright starts Next.js dev server.
+- Browser flow creates a comment and validates digest/signature changes.
+
+## Cloud sync (MCP log) — rerun commands
+```bash
+export DB_URL="https://<project>.db.co"
+export DB_SERVICE_ROLE_KEY="<service-role-key>"
+node mcp/tmp-log.mjs
+```
+Expected:
+- MCP tool connects and writes a task log entry for this acceptance run.
+
+## Evidence (this environment)
+- `npm run test:e2e:sandbox -- e2e/comments.spec.ts` failed (Next.js web server did not start; no URL visited):
+  - Command output:
+    - `> agx-cloud@0.1.0 test:e2e:sandbox`
+    - `> SANDBOX=1 CLOUD_SYNC_DISABLED=1 E2E_HOST=127.0.0.1 E2E_PORT=3100 playwright test e2e/comments.spec.ts`
+    - `[WebServer] (node:11097) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.`
+    - `[WebServer] (Use \`node --trace-warnings ...\` to show where the warning was created)`
+    - `[WebServer] ⚠ Warning: Next.js inferred your workspace root, but it may not be correct.`
+    - `[WebServer] We detected multiple lockfiles and selected the directory of /Users/mendrika/package-lock.json as the root directory.`
+    - `[WebServer] Detected additional lockfiles:`
+    - `[WebServer]   * /Users/mendrika/Projects/Agents/agx-cloud/package-lock.json`
+    - `[WebServer] (node:11098) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.`
+    - `[WebServer] (Use \`node --trace-warnings ...\` to show where the warning was created)`
+    - `[WebServer] ⨯ Failed to start server`
+    - `[WebServer] Error: listen EPERM: operation not permitted 127.0.0.1:3100`
+    - `[WebServer] at <unknown> (Error: listen EPERM: operation not permitted 127.0.0.1:3100) {`
+    - `[WebServer]   code: 'EPERM'`
+    - `[WebServer]   errno: -1`
+    - `[WebServer]   syscall: 'listen'`
+    - `[WebServer]   address: '127.0.0.1'`
+    - `[WebServer]   port: 3100`
+    - `[WebServer] }`
+    - `Error: Process from config.webServer exited early.`
+- `DB_URL=https://iicvrgtzktvsrestfqif.db.co DB_SERVICE_ROLE_KEY="<service-role-key>" node mcp/tmp-log.mjs` failed (IPC socket blocked):
+  - Command output:
+    - `Error: listen EPERM: operation not permitted /tmp/tsx-501/11143.pipe`
+    - `at Server.setupListenHandle [as _listen2] (node:net:1918:21)`
+    - `at listenInCluster (node:net:1997:12)`
+    - `at Server.listen (node:net:2119:5)`
+    - `at file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/tsx/dist/cli.mjs:53:31537`
+    - `code: 'EPERM' errno: -1 syscall: 'listen' address: '/tmp/tsx-501/11143.pipe'`
+    - `Node.js v25.5.0`
+    - `Failed to log via MCP: McpError: MCP error -32000: Connection closed`
+    - `at McpError.fromError (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js:2035:16)`
+    - `at Client._onclose (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js:259:32)`
+    - `at _transport.onclose (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js:223:18)`
+    - `at ChildProcess.<anonymous> (file:///Users/mendrika/Projects/Agents/agx-cloud/mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/client/stdio.js:85:31)`
+    - `at ChildProcess.emit (node:events:508:20)`
+    - `at maybeClose (node:internal/child_process:1084:16)`
+    - `at ChildProcess._handle.onexit (node:internal/child_process:304:5) {`
+    - `code: -32000`
+    - `data: undefined`
+    - `}`
+
+## Notes
+- Comments beginning with `[execution/` or `Execution result from agx` are excluded from prompt context.
+- Clients should treat signature/digest mismatch as fatal and re-pull task context before continuing execution.

package/cloud-runtime/standalone/notes/comments-context-plan.md

@@ -0,0 +1,119 @@
+# Comments as execution context (ideation)
+
+## Goal
+- Ensure task comments become first-class context that cloud-signed tasks hand to agents, and document the scope for the implementation work.
+
+## Current state summary
+- A dedicated `task_comments` table exists, plus a React timeline (`LogTimeline`) and API routes (`/api/tasks/[id]/comments`) to fetch/add comments.
+- `lib/task-context.ts` builds a prompt that already includes `COMMENTS` and computes a `comments_digest` that is injected into the signed payload in `/api/queue`.
+- The digest is covered by the HMAC implementation (`signTask`/`verifyTaskSignature`), and unit tests already assert digest changes affect the signature.
+
+## Identified gaps
+1. The MCP server (cloud API used by CLI/aggregator) still only returns task frontmatter; it neither fetches comment rows nor re-signs with digest, so CLI/agents pulling via MCP lose the context and security binding.
+2. Daemon/CLI workflows currently depend on db-reachable APIs; adding comment context requires confirming the aggregator pulls the new prompt/`comments_digest` instead of reusing stale signatures.
+3. There is no documented procedure for ensuring user comments trigger a new signed context before the daemon executes (the queue route handles it, but we should double-check aggregator flows). 
+
+## Progress since last review
+- `queue/pull` already builds and signs the full task context (prompt + `comments_digest`) when marking tasks as in_progress.
+- `tasks/get` now uses `buildTaskContext`, so MCP clients retrieving a task receive the same comment/learning context and digest that the queue path returns.
+- Added regression coverage for `/api/tasks/[id]` GET that mocks `buildTaskContext` and asserts the comments/`comments_digest` payload is merged before returning the task, ensuring the API surface matches what daemons receive.
+
+## Research takeaways (this turn)
+- `queue/pull` calls `buildTaskContext`, so each pull loads the latest comments/learnings/stage prompt, recomputes `comments_digest`, and re-signs (and persists) the task signature whenever the digest changes, keeping the daemon-bound payload consistent with on-disk comments.
+- `/api/queue` already has regression coverage showing that updating the digest triggers a new HMAC signature and persistence, which means any CLI/aggregator hitting that endpoint will automatically receive the refreshed signature once comments mutate.
+- `tasks/get` invokes `buildTaskContext` and merges the resulting prompt/digest into the API response, so MCP clients that re-fetch a task while waiting for work receive the same signed context the daemon executes with.
+- The same `buildTaskContext` helper is shared by `queue/pull` and `tasks/get`, ensuring future changes to comment rendering or digest computation stay in sync across daemon queue pulls and CLI/task fetches.
+
+
+## Updated approach
+1. Keep MCP queue pulls responsible for signing the comment-bound digest and persisting the new signature whenever the digest changes.
+2. Mirror the same context-building logic in MCP `tasks/get` so any client fetching a task still sees the digest and prompt the daemon will execute with.
+3. Document the expectations for comments as signed context, including how clients should handle new/edited comments (re-fetch, re-validate signature) and what happens if a comment arrives while the daemon is running.
+4. Surface tests (or test ideas) that exercise adding a comment, recomputing the digest, and ensuring the queued signature updates so we can catch regressions.
+
+## Signed comment expectations (cloud context)
+
+- `buildTaskContext` already concatenates the comments timeline, the current stage prompt, and required learnings before returning `comments_digest`. Any cloud-signed payload (`/api/queue`, `queue/pull`, etc.) must go through this helper so the daemon sees the most recent instructions.
+- When a user posts a comment through `/api/tasks/[id]/comments`, the route re-runs `buildTaskContext`, extracts the refreshed `comments_digest`, and re-signs the task before persisting it (see the `signTask` call inside the POST handler). That ensures the stored signature always reflects the comment set that will drive execution.
+- Clients that mutate comments—whether via the web UI or the MCP `tasks/log`/`tasks/comments` tools—should immediately re-fetch `/api/tasks/[id]` or the MCP `tasks/get` result to pull the rebuilt prompt, the new `comments_digest`, and the updated signature. If the signed payload differs from what the daemon previously received, treat it as a signal to halt the running work and pull again once the new context is verified.
+- Aggregators and daemons must continue to verify signatures on every queue pull. Because the signature covers `comments_digest`, replaying a cached signature after a comment change should surface as a verification failure, preventing execution with an outdated instruction set.
+- Operators should expect that comments can arrive mid-run; the safest workflow is to re-verify or re-pull whenever a comment mutation is observed, and to rely on the queue path’s automatic re-signing to keep the daemon-bound payload consistent.
+
+## Example request/response flows
+
+1. **Comment addition:**
+   - **Request:** `POST /api/tasks/123/comments` with body `{
+       "body": "Agent, please prioritize the new issue.",
+       "user_id": "user-abc"
+     }`.
+   - **Actions:** handler inserts the comment, calls `buildTaskContext(task)`, picks up the new `COMMENTS` section and digest, then signs the refreshed payload (including `comments_digest`) before updating `tasks.signature`.
+   - **Response:** `{
+       "id": 123,
+       "comments_digest": "sha256-xyz",
+       "signature": "hmac-abc",
+       "context": {
+         "prompt": "...COMMENTS...",
+         "comments": [...]
+       }
+     }` (clients should treat `signature`/`comments_digest` as the new ground truth and discard any cached payload tied to the previous digest).
+
+2. **Daemon queue pull:**
+   - **Request:** `POST /api/queue/pull` with daemon credentials and the task ID it is about to execute.
+   - **Actions:** queue route rebuilds the task context, recomputes `comments_digest`, and, if the digest differs from the stored value, re-signs and persists the task. The endpoint returns the signed payload so the daemon runs the latest prompt+comments.
+   - **Response:** same structure as the stored task but with the current `comments_digest` and `signature`. The daemon must verify the signature before executing and, if verification fails, abort and re-pull.
+
+3. **MCP task fetch:**
+   - **Request:** `GET /mcp/tasks/get?task_id=123` (or the equivalent CLI `tasks/get`).
+   - **Actions:** MCP `tasks.get` calls `buildTaskContext`, merges the `comments_digest` and prompt into the payload, and re-signs if necessary before returning.
+   - **Response:** `{
+       "task": {...},
+       "comments_digest": "sha256-xyz",
+       "signature": "hmac-abc",
+       "context": {...}
+     }`.
+
+## Failure handling & verification guidance
+
+- Clients (daemons, aggregators, or operators) that observe a comment mutation must treat signature/digest mismatches as fatal: do not proceed with the previously cached execution context. Instead, trigger a refresh (`/api/tasks/[id]` or `/api/queue/pull`) and verify the returned `signature` over the new `comments_digest` before continuing.
+- If signature verification fails even after re-fetching the task, assume the comment context may have been tampered with or left partially applied; log the failure, halt further execution, and surface the issue through the operator webhook/log stream so the issue can be investigated before retrying.
+- The queue pull endpoint already recomputes the digest, but daemons should still verify the signature locally to detect any corruption between the cloud response and their cached copy.
+- For MCP consumers that write comments via CLI tooling, ensure those commands re-fetch the signed task afterward so the digest and signature accompanying follow-on work are consistent; do not rely on eventual re-pulls alone since a new comment might be the trigger for higher-priority instructions.
+
+## Regression test checklist
+
+1. **`/api/tasks/[id]/comments` POST:**
+   - Mock `buildTaskContext` to return a digest that changes after the comment is inserted.
+   - Assert the route re-signs the task, persists the new `signature`, and includes the updated `comments_digest` in the response.
+   - Verify downstream handlers (e.g., task fetch) are supplied with the new digest as soon as the route completes.
+
+2. **`/api/queue/pull`:**
+   - Seed a task with an existing `comments_digest`/`signature`, then insert a comment that changes the digest.
+   - Confirm `queue/pull` recomputes the digest, re-signs the task, stores the new signature, and returns the refreshed `comments_digest` to the daemon.
+   - Ensure the daemon-side signature verification helper fails when presented with the old digest/signature pair (so we catch regressions where verification is skipped).
+
+3. **MCP `tasks/get` (cloud API):**
+   - Stub `buildTaskContext` to return different digests before and after a comment mutation.
+   - Assert the MCP helper merges the new `comments_digest` into the response and re-signs the payload before returning.
+   - Add an end-to-end test that simulates the CLI fetching a task after posting a comment and verifies the signature verification step accepts the new digest and rejects the old one.
+
+4. **Tooling/verification notes:**
+   - Tests need low-level access to `signTask`/`verifyTaskSignature` to assert a digest change truly rotates the signature; stubbed helpers should mirror the production logic, otherwise we risk false positives.
+   - Logging or metric hooks should capture signature verification failures so we can detect clients that skip the re-fetch cycle; add assertions in tests that the failure path is exercised when mismatched signatures appear.
+
+## Effort estimate
+- MCP server enhancement (prompt generation + digest handling): 1.5–2 days
+- Tests/documentation + stash/hand-off notes: 0.5 day
+- Total: ~2–2.5 working days (assuming no additional infra blockers).
+
+## Unknowns / questions
+- Does the CLI/aggregator currently read the MCP `task.signature` and verify it before execution, or will we need to update it to replay the new digest?
+- Are there any other sources of editable context (e.g., learnings or logs) that also need digesting in the same signed payload?
+- What user_id should new comments/learnings be attached to when we insert/update them via MCP (the cloud API)?
+- Are there rate limits or permission guardrails that will prevent us from re-signing tasks with new digests on every pull?
+- Should there be an explicit signal (webhook, SSE, etc.) to the daemon/aggregator when comments change so we can safely abort the current execution and re-pull the refreshed signature?
+- Do comment edits (not just additions) automatically move through the same digest/resign flow, or do we need an extra hook for edit operations?
+
+## Next concrete steps
+1. (Done) Expanded regression coverage by adding a MCP queue/pull test that ensures `comments_digest` changes trigger re-signing and persistence in the MCP workflow.
+2. (Done) Document the signed-comment expectations for clients/operators, covering the re-fetch workflow, required validation steps, and how daemons should behave when a comment arrives while running.
+3. Validate aggregator/daemon signature verification flow end-to-end and capture any outstanding requirements before moving to planning/coding.

package/cloud-runtime/standalone/notes/context-audit.md

@@ -0,0 +1,21 @@
+# Context handling audit
+
+## agx-cloud
+
+- `lib/task-context.ts` builds the signed execution context sent to agents. It gathers comments for a task, fetches learnings scoped to the task/project/global buckets, resolves the stage prompt from `stage_prompts`, and then renders a multi-section prompt (`STAGE PROMPT`, `TASK META`, `COMMENTS`, `LEARNINGS (task|project|global)`). The resulting `TaskContext` (prompt + `comments_digest`) is spread into the responses from `/api/tasks`, `/api/queue`, and several MCP helpers so daemons/agx cli receive all the metadata they need before executing a stage.
+- The current schema only stores a loose `project` string per task; there is no structured project record or repo metadata backing `project_context`, so anything beyond the simple label is runtime-only and held in notes (see `notes/project-layer.md`).
+- APIs such as `app/api/tasks/route.ts`, `/api/tasks/[id]/comments`, and the MCP CLI (`mcp/src/tools/*.ts`) all call `buildTaskContext`, meaning the pipeline already supports injecting richer context if we extend the helper.
+
+## agx CLI
+
+- `lib/executor.js` builds stage prompts entirely on the CLI side. It reads a stage name from the task metadata, looks up `STAGE_CONFIG` to retrieve the hard-coded instructions (e.g., "Create detailed plan with tasks, milestones, and dependencies" for planning), and then emits a `buildPrompt` that wraps the static prompt, the full task content, and a fixed instruction list (`[checkpoint]`, etc.). No cloud-provided context or learnings are merged in.
+- Tasks created with `agx new` collect frontmatter that includes the `project` string (`index.js` around lines 2976-3025), but the CLI only ships that text as part of the task payload; it does not know anything about repo paths, CI/CD hints, or aggregated learnings tied to a project entity.
+- Helper scripts like `lib/worker.js` and `lib/realtime.js` print the raw `project` label when reporting progress, but they never refer to a richer project object or project-specific metadata.
+
+## Gaps to close for the new project layer
+
+1. The CLI has no way to request or receive structured `project_context` data (repo mapping, CI/CD notes, stack learnings) when invoking a task; it simply reruns the stale frontmatter/stage prompt mix that predates the planned feature.
+2. The cloud already centralizes comments, stage prompts, and learnings via `buildTaskContext`, so extending that helper to add project metadata would give every downstream caller the enriched view we need, but the current schema/API surface lacks a `projects` entity to base that metadata on.
+3. We must define how a project is stored (schema/migrations), how tasks learn of their parent project (FK, slug, etc.), and how the CLI/daemon request it when building prompts.
+
+Next action: finish this audit by matching whichever `lib/db` helpers and DB migrations will need updates so we can define the new `projects` and `project_repos` tables with the right FK relationships.

package/cloud-runtime/standalone/notes/project-layer-plan.md

@@ -0,0 +1,30 @@
+# Project layer plan for agx-cloud agx-agent flow
+
+## Summary
+- Capture how the CLI/daemon should obtain and surface structured project metadata, repo mapping, CI/CD hints, and learnings so that agents execute with a consistent context from idea through release.
+- Define the data model, API surfaces, and prompt pipeline changes needed to treat projects as first-class entities shared between agx-cloud, agx CLI, and MCP/daemon workloads.
+
+## Task breakdown
+| ID | Task | Details | Dependencies | Owner | Effort |
+| --- | --- | --- | --- | --- | --- |
+| T1 | Schema & FK design | Define `projects` + `project_repos`, link `tasks`/`learnings` to `project_id`, and sketch migrations + RLS updates. | None | Backend | 2d |
+| T2 | Project APIs & MCP enrichment | Add CRUD endpoints, ensure `/api/tasks` + `/api/queue` embed `project_context`, and extend MCP helpers (`tasks.get`, `queue.pull`) and `buildTaskContext`. | T1 | Backend | 2d |
+| T3 | CLI/daemon prompt flow | Pass `project_context` through `agx run/new` + `lib/executor.js`, render `PROJECT CONTEXT` + `REPO MAP`, and make learnings resolve project-scoped history. | T2 | CLI | 1d |
+| T4 | Cloud UI surfaces | Add project management views/forms, show context/CI status in dashboard/task detail, and link learnings to projects. | T2 | Frontend | 1.5d |
+| T5 | Testing & documentation | Update regression tests (task context, MCP) and document how project context flows; detail how CLI/UI should refresh when project metadata changes. | T2, T3, T4 | Full stack | 1d |
+
+## Milestones
+1. **Foundation (Deadline TBD)** – Schema/migration + API surfaces exist, ensuring `project_context` can be signed and delivered to any task consumer. 
+2. **Context surfaces** – CLI/daemon prompts and cloud UI display the enriched project metadata so agents have repo mappings, CI/CD info, and learnings. 
+3. **Rollout + coverage** – Tests/docs updated, learnings pipeline scoped to projects, and rollout notes outline how to migrate existing tasks.
+
+## Dependencies
+- Schema migration must precede any backend or CLI work that references `projects`/`project_repos` columns.
+- MCP helpers and `buildTaskContext` need the final project payload before CLI/daemon prompt changes are merged.
+- Frontend components use the new APIs, so backend endpoints must be ready before the UI surfaces can be wired.
+- Learnings pipeline relies on a stable project identifier; ensure `scope_id` updates once the project row exists.
+
+## Next concrete steps
+1. Solidify the migration SQL and update `lib/db` helpers/policies to expose `projects` + `project_repos` with the necessary joins.
+2. Extend `buildTaskContext` and the MCP helpers to include the new `project_context` section so every agent sees the metadata.
+3. Note that cloud API sync (writing to DB) will validate once the schema and MCP endpoints are running; record the plan via the MCP task log or equivalent once the server is accessible.