@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/intake/daemon.mjs

@@ -6,6 +6,13 @@
  * Packets past their TTL move to `.cx/intake/dead-letter/`; failed
  * classification retries up to the budget then dead-letters with the reason.
  *
+ * Every tick also sweeps the persisted `.cx/intake/pending/` packets
+ * (sweepPendingPackets): a packet whose `intake.sourcePath` is missing from
+ * disk, or whose age exceeds classifyPacket's TTL, moves to
+ * `.cx/intake/dead-letter/` with a `deadLetterReason`. This covers persisted
+ * packets, not just in-flight inbox files, so the TTL/dead-letter contract
+ * above applies to the whole pending queue.
+ *
  * Atomic handoff (ADR-0045 §C): only complete top-level files are enqueued.
  * Dotfiles and the `inbox/.staging/` assembly directory are skipped, so a file
  * a writer is still staging is invisible until it is renamed into `inbox/`.
@@ -14,18 +21,19 @@
  * idle shutdown, heartbeat, killswitch, single-writer lock) applies.
  */
 
-import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 
 import { createDaemon, classifyPacket } from '../daemons/contract.mjs';
 import { memoryCapMbFor } from '../resources/process-budget.mjs';
+import { resolveStatePath } from '../state-root.mjs';
 
 const KILLSWITCH_ENV = 'CONSTRUCT_INTAKE_DAEMON';
 
 function inboxDir(cwd) { return join(cwd, 'inbox'); }
 function pendingDir(cwd) { return join(cwd, '.cx', 'intake', 'pending'); }
 function deadLetterDir(cwd) { return join(cwd, '.cx', 'intake', 'dead-letter'); }
-function heartbeatPath(cwd) { return join(cwd, '.cx', 'runtime', 'intake-daemon.heartbeat'); }
+function heartbeatPath(cwd) { return resolveStatePath(cwd, 'runtime', 'intake-daemon.heartbeat'); }
 
 function ensureDir(dir) {
   try { mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
@@ -60,9 +68,55 @@ function listInboxFiles(cwd) {
     .filter((full) => isSizeStable(full));
 }
 
+function pendingPacketFiles(cwd) {
+  const dir = pendingDir(cwd);
+  if (!existsSync(dir)) return [];
+  try { return readdirSync(dir).filter((name) => name.endsWith('.json')); }
+  catch { return []; }
+}
+
+function readPacketFile(cwd, name) {
+  try { return JSON.parse(readFileSync(join(pendingDir(cwd), name), 'utf8')); }
+  catch { return null; }
+}
+
+function packetSourcePath(packet) {
+  return packet?.intake?.sourcePath || packet?.sourcePath || null;
+}
+
+function packetFirstSeenAt(packet) {
+  return packet?.firstSeenAt || packet?.createdAt || null;
+}
+
+// processInboxFile renames its source into a `.<name>.consumed` marker inside
+// pendingDir once a packet is written, so the original sourcePath disappears
+// the moment ingestion succeeds. That disappearance is expected, not an
+// orphan — the sweep must not dead-letter a packet on the very next tick
+// just because its own consumption already moved the source out of the way.
+
+function hasConsumedMarker(cwd, sourcePath) {
+  return existsSync(join(pendingDir(cwd), `.${basename(sourcePath)}.consumed`));
+}
+
+// A pending packet is keyed by the source file it came from, independent of
+// which ingest path wrote it (flat `sourcePath` here, nested
+// `intake.sourcePath` for packets from lib/intake/prepare.mjs). Finding a
+// live match lets re-ingestion refresh in place instead of writing a sibling
+// packet for the same source.
+
+function findExistingPendingBySource(cwd, sourcePath) {
+  for (const name of pendingPacketFiles(cwd)) {
+    const data = readPacketFile(cwd, name);
+    if (data && packetSourcePath(data) === sourcePath) return { name, data };
+  }
+  return null;
+}
+
 /**
  * Process one inbox file: classify, persist packet to pending, remove the
  * inbox source on success, or move to dead-letter on persistent failure.
+ * A file whose sourcePath already has a live pending packet refreshes that
+ * packet in place rather than writing a second one for the same source.
  *
  * Returns one of:
  *   { didWork: true,  route: 'pending'|'dead-letter', packetId }
@@ -76,10 +130,11 @@ export async function processInboxFile(filePath, { cwd, classify, now = () => ne
   try { body = readFileSync(filePath, 'utf8'); }
   catch (err) { return { didWork: false, reason: `read failed: ${err.message}` }; }
 
-  const id = `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
+  const existing = findExistingPendingBySource(cwd, filePath);
+  const id = existing?.data?.id || `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
   const packet = {
     id,
-    firstSeenAt: new Date(statSync(filePath).mtimeMs).toISOString(),
+    firstSeenAt: existing?.data?.firstSeenAt || new Date(statSync(filePath).mtimeMs).toISOString(),
     sourcePath: filePath,
     excerpt: body.slice(0, 500),
     attempts: 0,
@@ -101,13 +156,15 @@ export async function processInboxFile(filePath, { cwd, classify, now = () => ne
     return { didWork: false, reason: `classify failed, will retry: ${err.message}` };
   }
 
-  const packetPath = join(pendingDir(cwd), `${id}.json`);
+  packet.lastSeenAt = now().toISOString();
+  const packetName = existing?.name || `${id}.json`;
+  const packetPath = join(pendingDir(cwd), packetName);
   writeFileSync(packetPath, JSON.stringify(packet, null, 2));
   try {
     const consumedPath = join(pendingDir(cwd), `.${basename(filePath)}.consumed`);
     renameSync(filePath, consumedPath);
   } catch { /* ignore consume failure */ }
-  return { didWork: true, route: 'pending', packetId: id };
+  return { didWork: true, route: 'pending', packetId: id, refreshed: !!existing };
 }
 
 function persistDeadLetter(filePath, packet, reason, cwd) {
@@ -117,6 +174,40 @@ function persistDeadLetter(filePath, packet, reason, cwd) {
   return { didWork: true, route: 'dead-letter', packetId: packet.id, reason };
 }
 
+/**
+ * Sweep persisted `.cx/intake/pending/` packets: one whose source file is
+ * missing from disk, or whose age exceeds classifyPacket's TTL, moves to
+ * `.cx/intake/dead-letter/` with a `deadLetterReason`. Runs every tick
+ * alongside the inbox scan so packets written by any ingest path (not just
+ * processInboxFile) are covered — the daemon's TTL/dead-letter contract
+ * otherwise only reaches packets still in flight through the inbox.
+ *
+ * Returns the list of { id, reason } packets moved.
+ */
+export function sweepPendingPackets(cwd, { now = () => new Date() } = {}) {
+  const swept = [];
+  for (const name of pendingPacketFiles(cwd)) {
+    const packet = readPacketFile(cwd, name);
+    if (!packet) continue;
+
+    const sourcePath = packetSourcePath(packet);
+    const sourceMissing = !!sourcePath && !existsSync(sourcePath) && !hasConsumedMarker(cwd, sourcePath);
+    const decision = classifyPacket({ firstSeenAt: packetFirstSeenAt(packet), attempts: packet.attempts || 0 });
+
+    let reason = null;
+    if (sourceMissing) reason = 'source-missing';
+    else if (decision.route === 'dead-letter') reason = 'ttl-expired';
+    if (!reason) continue;
+
+    ensureDir(deadLetterDir(cwd));
+    const dlPath = join(deadLetterDir(cwd), name);
+    writeFileSync(dlPath, JSON.stringify({ ...packet, deadLetterReason: reason, deadLetteredAt: now().toISOString() }, null, 2));
+    try { unlinkSync(join(pendingDir(cwd), name)); } catch { /* leave the dead-letter copy even if cleanup fails */ }
+    swept.push({ id: packet.id || name.replace(/\.json$/, ''), reason });
+  }
+  return swept;
+}
+
 /**
  * Build a DaemonRunner for the intake daemon. Caller is responsible for
  * calling .run() — typically construct intake daemon start.
@@ -132,9 +223,9 @@ export function buildIntakeDaemon({ cwd = process.cwd(), intervalMs = 60_000, cl
     maxIdleTicks: 6,
     memoryCapMb: memoryCapMbFor('intake', cwd),
     async tick() {
+      const swept = sweepPendingPackets(cwd);
       const files = listInboxFiles(cwd);
-      if (files.length === 0) return { didWork: false };
-      let workedAny = false;
+      let workedAny = swept.length > 0;
       for (const file of files) {
         const result = await processInboxFile(file, { cwd, classify: classifyFn });
         if (result.didWork) workedAny = true;

package/lib/intake/git-queue.mjs

@@ -4,6 +4,18 @@
  * Backs team/enterprise modes with the filesystem and Git for state
  * synchronization and conflict resolution, with no central database server.
  *
+ * git-queue is the zero-dependency DEFAULT kind:'queue' provider
+ * (construct-9oi4.7.11); substrate owns the queue contract and Postgres is an
+ * optional provider selected through the extension registry.
+ *
+ * Correctness envelope: single-writer-preferred, eventual consistency.
+ * Concurrent claims from multiple agents may result in duplicate claim
+ * attempts; the dolt commit history provides reconciliation. A push failure is
+ * NOT swallowed or ratified as success: claim() returns a typed disposition
+ * ({ durable: false, disposition: 'local-only', reason }) so callers see that
+ * the claim is local-only until the push is confirmed in the dolt remote,
+ * rather than mistaking it for a durable claim.
+ *
  * Structure:
  * .cx/team-inbox/
  *   pending/    - JSON files for unclaimed tasks
@@ -34,9 +46,11 @@ function timestamp() {
 }
 
 export class GitIntakeQueue {
-  constructor({ project, rootDir = process.cwd() } = {}) {
+  constructor({ project, rootDir = process.cwd(), _exec } = {}) {
     this.project = project;
     this.inboxRoot = path.join(rootDir, '.cx', 'team-inbox');
+    // Allow tests to inject a fake exec without monkey-patching the module.
+    this._exec = _exec || execSync;
     this._ensureDirs();
   }
 
@@ -48,8 +62,8 @@ export class GitIntakeQueue {
 
   _gitAddAndCommit(filePath, message) {
     try {
-      execSync(`git add "${filePath}"`, { stdio: 'ignore' });
-      execSync(`git commit -m "${message}"`, { stdio: 'ignore' });
+      this._exec(`git add "${filePath}"`, { stdio: 'ignore' });
+      this._exec(`git commit -m "${message}"`, { stdio: 'ignore' });
     } catch (err) {
       // It's okay if commit fails because of no changes
     }
@@ -93,17 +107,24 @@ export class GitIntakeQueue {
   }
 
   async read(id) {
-    for (const dir of ['pending', 'claimed', 'processed', 'skipped', 'quarantine']) {
-      // Note: 'claimed' has subdirs, we'd need to search recursively for claimed.
-      // For simplicity in this implementation, we assume we know where it is or search pending first.
-      const searchPath = dir === 'claimed' 
-        ? path.join(this.inboxRoot, dir) // needs recursive search
-        : path.join(this.inboxRoot, dir, `${id}.json`);
-      
-      if (dir !== 'claimed' && fs.existsSync(searchPath)) {
+    for (const dir of ['pending', 'processed', 'skipped', 'quarantine']) {
+      const searchPath = path.join(this.inboxRoot, dir, `${id}.json`);
+      if (fs.existsSync(searchPath)) {
         return JSON.parse(fs.readFileSync(searchPath, 'utf8'));
       }
     }
+
+    // 'claimed' uses per-worker subdirectories — search recursively.
+    const claimedBase = path.join(this.inboxRoot, 'claimed');
+    if (fs.existsSync(claimedBase)) {
+      for (const worker of fs.readdirSync(claimedBase)) {
+        const candidate = path.join(claimedBase, worker, `${id}.json`);
+        if (fs.existsSync(candidate)) {
+          return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+        }
+      }
+    }
+
     return null;
   }
 
@@ -111,8 +132,13 @@ export class GitIntakeQueue {
     if (!claimedBy) throw new Error('claim: claimedBy is required');
     
     // Pull latest to minimize conflicts
-
-    try { execSync('git pull --rebase', { stdio: 'ignore' }); } catch (e) {}
+    try {
+      this._exec('git pull --rebase', { stdio: 'ignore' });
+    } catch (pullErr) {
+      // Pull failure is non-fatal — we proceed with local state.
+      // Log a reconciliation record so operators can detect divergence.
+      console.warn(`[git-queue] pull failed before claim (proceeding with local state): ${pullErr.message}`);
+    }
 
     const pendingDir = path.join(this.inboxRoot, 'pending');
     const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.json')).sort();
@@ -125,31 +151,34 @@ export class GitIntakeQueue {
     fs.mkdirSync(workerDir, { recursive: true });
     const claimedPath = path.join(workerDir, fileName);
 
-    try {
-      // Atomic move on filesystem
-      fs.renameSync(pendingPath, claimedPath);
-      
-      // Update metadata
-      const data = JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
-      data.status = 'claimed';
-      data.claimedBy = claimedBy;
-      data.claimedAt = new Date().toISOString();
-      fs.writeFileSync(claimedPath, JSON.stringify(data, null, 2));
-
-      // Commit and push the claim so peers see it
-
-      execSync(`git add .cx/team-inbox/pending/${fileName} .cx/team-inbox/claimed/${claimedBy}/${fileName}`, { stdio: 'ignore' });
-      execSync(`git commit -m "Claim task ${data.id} by ${claimedBy}"`, { stdio: 'ignore' });
-      execSync('git push', { stdio: 'ignore' });
-
-      return data;
-    } catch (err) {
-      // A push failure means another worker claimed it first or Git is out of
-      // sync; the local move is left for the next 'git pull --rebase' to reconcile.
+    // Atomic move on filesystem
+    fs.renameSync(pendingPath, claimedPath);
+
+    // Update metadata
+    const data = JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
+    data.status = 'claimed';
+    data.claimedBy = claimedBy;
+    data.claimedAt = new Date().toISOString();
+    fs.writeFileSync(claimedPath, JSON.stringify(data, null, 2));
 
-      console.error(`Failed to claim ${fileName}: ${err.message}`);
-      return null;
+    // Commit and push the claim so peers see it. A push failure is reported as a
+    // typed non-durable disposition on the returned claim rather than swallowed:
+    // the local move stands for the next 'git pull --rebase' to reconcile, but
+    // the caller is told the claim is local-only, not durable.
+    data.durable = true;
+    data.disposition = 'pushed';
+    try {
+      this._exec(`git add .cx/team-inbox/pending/${fileName} .cx/team-inbox/claimed/${claimedBy}/${fileName}`, { stdio: 'ignore' });
+      this._exec(`git commit -m "Claim task ${data.id} by ${claimedBy}"`, { stdio: 'ignore' });
+      this._exec('git push', { stdio: 'ignore' });
+    } catch (pushErr) {
+      data.durable = false;
+      data.disposition = 'local-only';
+      data.dispositionReason = pushErr.message;
+      console.warn(`[git-queue] push failed after claim of ${data.id} by ${claimedBy} (claim is local-only until reconciled): ${pushErr.message}`);
     }
+
+    return data;
   }
 
   async markProcessed(id, { processedBy = 'unknown', notes = '' } = {}) {
@@ -187,10 +216,53 @@ export class GitIntakeQueue {
     fs.writeFileSync(processedPath, JSON.stringify(data, null, 2));
 
     this._gitAddAndCommit(this.inboxRoot, `Mark task ${id} as processed`);
-    try { execSync('git push', { stdio: 'ignore' }); } catch (e) {}
+    try { this._exec('git push', { stdio: 'ignore' }); } catch (e) {}
 
     return { id };
   }
 
-  // markSkipped and reopen would follow similar logic...
+  /**
+   * Mark an issue as skipped in local state WITHOUT a push.
+   *
+   * Used for graceful degradation when a push fails or when the caller wants
+   * to skip without touching the remote.  The skip is advisory — it survives
+   * only as a local file move until the next reconciliation pull.
+   *
+   * @param {string} issueId
+   * @returns {{ id: string, skippedAt: string }}
+   */
+  async markSkipped(issueId) {
+    if (!issueId) throw new Error('markSkipped: issueId is required');
+
+    // Locate the file across pending and claimed directories.
+    let foundPath = null;
+
+    const pendingCandidate = path.join(this.inboxRoot, 'pending', `${issueId}.json`);
+    if (fs.existsSync(pendingCandidate)) {
+      foundPath = pendingCandidate;
+    } else {
+      const claimedBase = path.join(this.inboxRoot, 'claimed');
+      if (fs.existsSync(claimedBase)) {
+        for (const worker of fs.readdirSync(claimedBase)) {
+          const candidate = path.join(claimedBase, worker, `${issueId}.json`);
+          if (fs.existsSync(candidate)) { foundPath = candidate; break; }
+        }
+      }
+    }
+
+    if (!foundPath) throw new Error(`markSkipped: no entry ${issueId} found`);
+
+    const data = JSON.parse(fs.readFileSync(foundPath, 'utf8'));
+    data.status = 'skipped';
+    data.skippedAt = new Date().toISOString();
+
+    const skippedPath = path.join(this.inboxRoot, 'skipped', `${issueId}.json`);
+    fs.renameSync(foundPath, skippedPath);
+    fs.writeFileSync(skippedPath, JSON.stringify(data, null, 2));
+
+    // No push — this is a local-only operation (graceful degradation).
+    return { id: issueId, skippedAt: data.skippedAt };
+  }
+
+  // reopen would follow similar logic...
 }

package/lib/intake/queue-registry.mjs

@@ -0,0 +1,50 @@
+/**
+ * lib/intake/queue-registry.mjs — kind:'queue' provider resolution.
+ *
+ * Substrate owns the queue/run-store CONTRACT; git-queue is the zero-dependency
+ * DEFAULT provider and Postgres is an OPTIONAL provider. Selection is explicit:
+ * a concrete queue backend is chosen by resolving an installed kind:'queue'
+ * manifest through the extension registry (construct-9oi4.7.11, supersedes the
+ * ADR-0051 git-vs-postgres framing). No silent postgres->git alias exists — a
+ * caller that names a backend with no registered kind:'queue' provider gets a
+ * typed error, not a swallowed downgrade.
+ *
+ * Resolution surface:
+ *   listQueueProviders({ rootDir, env }) → manifest[] of kind:'queue', merged
+ *     across builtin/user/project tiers (project wins).
+ *   findQueueProvider(backend, { rootDir, env }) → manifest | null for a backend id.
+ */
+
+import { loadManifestsFromDir, mergeManifests, resolveManifestDirs } from '../extensions/loader.mjs';
+
+/**
+ * The queue backend ids that are always resolvable without a registered
+ * manifest. git is the default provider; filesystem is the solo-mode default
+ * provider. Both ship in-tree, so they never require an extension manifest.
+ */
+export const BUILTIN_QUEUE_BACKENDS = ['git', 'filesystem'];
+
+// Load every kind:'queue' manifest across the three tiers and merge by id so a
+// project- or user-level Postgres queue provider overrides a builtin of the
+// same id. Only manifests declaring kind:'queue' are returned.
+
+export function listQueueProviders({ rootDir = process.cwd(), env = process.env } = {}) {
+  const homeDir = env?.HOME || env?.USERPROFILE || undefined;
+  const dirs = resolveManifestDirs({ rootDir, homeDir });
+  const builtin = loadManifestsFromDir(dirs.builtin).manifests;
+  const user = loadManifestsFromDir(dirs.user).manifests;
+  const project = loadManifestsFromDir(dirs.project).manifests;
+  return mergeManifests(builtin, user, project).filter((m) => m.kind === 'queue');
+}
+
+/**
+ * findQueueProvider(backend, opts)
+ *
+ * Returns the kind:'queue' manifest whose id matches `backend`, or null when no
+ * such provider is registered. Callers use the null result to distinguish an
+ * unregistered backend (a hard, explicit error) from a resolvable one.
+ */
+export function findQueueProvider(backend, { rootDir = process.cwd(), env = process.env } = {}) {
+  if (!backend) return null;
+  return listQueueProviders({ rootDir, env }).find((m) => m.id === backend) || null;
+}

package/lib/intake/queue.mjs

@@ -3,14 +3,20 @@
  *
  * The IntakeQueue contract carries the R&D intake packets from the embed
  * daemon (writer) to the agent in the user's editor (reader/processor).
- * Solo mode is backed by the filesystem under `.cx/intake/`; team and
- * enterprise modes are backed by Postgres with row-locked worker claims.
- * Callers never branch on backend — they ask for a queue via
- * `createIntakeQueue(rootDir, env)` and use the same six methods.
+ * Substrate owns the queue CONTRACT; git-queue is the zero-dependency default
+ * kind:'queue' provider and Postgres is an optional kind:'queue' provider
+ * selected through the extension registry (construct-9oi4.7.11). Solo mode
+ * resolves to the filesystem provider under `.cx/intake/`; team and enterprise
+ * default to the Postgres provider. Callers never branch on backend — they ask for a
+ * queue via `createIntakeQueue(rootDir, env)` and use the same six methods.
+ * The returned instance also carries `.tenantId` (ADR-0057/A7: resolved once
+ * from CONSTRUCT_TENANT_ID/config, 'local' default outside enterprise mode)
+ * so a caller can stamp it onto entries without re-resolving it.
  *
  * Queue entry shape:
  *   {
  *     id, createdAt, status: 'pending'|'processed'|'skipped',
+ *     tenantId?,
  *     intake: { sourcePath, outputPath, characters, knowledgeSubdir },
  *     triage: { intakeType, rdStage, primaryOwner, recommendedChain,
  *               recommendedAction, risk, requiresApproval, confidence,
@@ -37,19 +43,60 @@ import path from 'node:path';
 
 import { FilesystemIntakeQueue, queueRoot, pendingDir, processedDir, skippedDir } from './filesystem-queue.mjs';
 import { GitIntakeQueue } from './git-queue.mjs';
-import { getDeploymentMode } from '../deployment-mode.mjs';
+import {
+  getDeploymentMode,
+  requireTeamCapabilityOrDegrade,
+} from '../deployment-mode.mjs';
+import { createSqlClient } from '../storage/backend.mjs';
+import { findQueueProvider, BUILTIN_QUEUE_BACKENDS } from './queue-registry.mjs';
+import { resolveTenantContext, TENANT_ID_ENV_KEY, DEFAULT_TENANT_ID } from '../tenant/context.mjs';
+import { PostgresIntakeQueue } from '../queue/pg-queue.mjs';
 
 export { FilesystemIntakeQueue, GitIntakeQueue, queueRoot, pendingDir, processedDir, skippedDir };
 
 export const INTAKE_QUEUE_BACKEND_ENV_KEY = 'CONSTRUCT_INTAKE_QUEUE_BACKEND';
 export const INTAKE_PROJECT_ENV_KEY = 'CONSTRUCT_PROJECT_NAME';
 export const INTAKE_TENANT_ENV_KEY = 'CONSTRUCT_TENANT_ID';
+export const INTAKE_QUEUE_NAME_ENV_KEY = 'CONSTRUCT_INTAKE_QUEUE_NAME';
+export const INTAKE_QUEUE_LEASE_SECONDS_ENV_KEY = 'CONSTRUCT_QUEUE_LEASE_SECONDS';
 
-function resolveBackend(env) {
+// Re-exported so a caller can resolve the same tenant value the factory
+// stamps on the queue without importing lib/tenant/context.mjs directly.
+export { TENANT_ID_ENV_KEY, DEFAULT_TENANT_ID } from '../tenant/context.mjs';
+
+// Thrown when a caller names a queue backend that is neither a builtin provider
+// (git/filesystem) nor a registered kind:'queue' extension. The reframing
+// removed the silent postgres->git alias, so an unknown backend is a hard,
+// explicit error rather than a swallowed downgrade.
+
+export class UnregisteredQueueProviderError extends Error {
+  constructor(backend) {
+    super(
+      `Queue backend '${backend}' has no registered kind:'queue' provider. ` +
+      `Builtin providers: ${BUILTIN_QUEUE_BACKENDS.join(', ')}. ` +
+      `Install a kind:'queue' extension (e.g. a Postgres provider) to select it.`,
+    );
+    this.name = 'UnregisteredQueueProviderError';
+    this.backend = backend;
+  }
+}
+
+// Selection resolves through the registry by kind. An explicit backend override
+// wins; otherwise deployment mode picks the default provider (solo→filesystem,
+// team/enterprise→postgres). A non-builtin backend must resolve to a registered
+// kind:'queue' provider or the call fails explicitly.
+
+function resolveBackend(env, rootDir) {
   const override = env?.[INTAKE_QUEUE_BACKEND_ENV_KEY];
-  if (override === 'filesystem' || override === 'git') return override;
-  const mode = getDeploymentMode(env);
-  return mode === 'solo' ? 'filesystem' : 'git';
+  const requested = override && String(override).trim()
+    ? String(override).trim()
+    : (getDeploymentMode(env, { cwd: rootDir }) === 'solo' ? 'filesystem' : 'postgres');
+
+  if (BUILTIN_QUEUE_BACKENDS.includes(requested)) return { backend: requested, provider: null };
+
+  const provider = findQueueProvider(requested, { rootDir, env });
+  if (!provider) throw new UnregisteredQueueProviderError(requested);
+  return { backend: requested, provider };
 }
 
 function resolveProject(rootDir, env) {
@@ -58,20 +105,89 @@ function resolveProject(rootDir, env) {
   return path.basename(path.resolve(rootDir)).trim() || 'construct';
 }
 
+// Resolves the tenant context (config + env, validated) for queue scoping.
+// Reads CONSTRUCT_TENANT_ID directly here — the factory is a plumbing
+// boundary, so it does not load construct.config.json itself and passes no
+// config, which mirrors solo/team's config-optional path. Enterprise callers
+// that need config-sourced tenantId should resolve it once at startup via
+// lib/deployment-mode.mjs#validateTenantAtStartup and pass the result through
+// opts.tenantId instead of relying on this fallback.
+
+export function resolveIntakeTenantId(env = process.env, mode = getDeploymentMode(env)) {
+  return resolveTenantContext({ env, mode }).tenantId;
+}
+
 /**
  * Create an IntakeQueue instance for the given project root.
  * Backend selection: CONSTRUCT_INTAKE_QUEUE_BACKEND override wins; otherwise
- * solo mode → filesystem, team/enterprise → git. The git
- * backend uses the filesystem and git for state synchronization.
+ * solo mode → filesystem, team/enterprise → postgres. A backend that is neither builtin nor a registered
+ * kind:'queue' provider throws UnregisteredQueueProviderError — there is no
+ * silent postgres->git alias.
+ *
+ * The returned instance carries a `.tenantId` (opts.tenantId wins, otherwise
+ * resolved from CONSTRUCT_TENANT_ID/config via resolveIntakeTenantId) so a
+ * caller building a queue entry can stamp tenantId without re-deriving it —
+ * the queue classes themselves stay tenant-agnostic (LMCP-H1; tenant-scoped
+ * storage is LMCP-H4, not this bead).
  */
 export function createIntakeQueue(rootDir, env = process.env, opts = {}) {
-  const backend = opts.backend || resolveBackend(env);
-  if (backend === 'filesystem') return new FilesystemIntakeQueue(rootDir);
-  if (backend === 'git' || backend === 'postgres') {
-    // 'postgres' aliases to 'git' so existing configs keep resolving
+  const resolved = opts.backend
+    ? (BUILTIN_QUEUE_BACKENDS.includes(opts.backend)
+        ? { backend: opts.backend, provider: null }
+        : (findQueueProvider(opts.backend, { rootDir, env })
+            ? { backend: opts.backend, provider: findQueueProvider(opts.backend, { rootDir, env }) }
+            : (() => { throw new UnregisteredQueueProviderError(opts.backend); })()))
+    : resolveBackend(env, rootDir);
 
+  const tenantId = opts.tenantId ?? resolveIntakeTenantId(env, getDeploymentMode(env, { cwd: rootDir }));
+
+  if (resolved.backend === 'filesystem') {
+    const queue = new FilesystemIntakeQueue(rootDir);
+    queue.tenantId = tenantId;
+    return queue;
+  }
+  if (resolved.backend === 'git') {
     const project = opts.project ?? resolveProject(rootDir, env);
-    return new GitIntakeQueue({ project, rootDir });
+    const queue = new GitIntakeQueue({ project, rootDir });
+    queue.tenantId = tenantId;
+    return queue;
   }
-  throw new Error(`Unknown intake queue backend: ${backend}`);
+
+  if (resolved.backend === 'postgres' || resolved.provider?.id === 'postgres') {
+    const sql = opts.sql ?? createSqlClient(env);
+    if (!sql) {
+      const mode = getDeploymentMode(env, { cwd: rootDir });
+      if (mode === 'solo') {
+        throw new Error(
+          `Queue backend '${resolved.backend}' requires DATABASE_URL or CONSTRUCT_DATABASE_URL; ` +
+          `no Postgres SQL client is configured.`,
+        );
+      }
+      requireTeamCapabilityOrDegrade('postgres-queue', false, env, { cwd: rootDir });
+      const queue = new GitIntakeQueue({ project: opts.project ?? resolveProject(rootDir, env), rootDir });
+      queue.tenantId = tenantId;
+      queue.backend = 'git';
+      queue.requestedBackend = resolved.backend;
+      queue.degraded = true;
+      queue.degradedReason = 'postgres-unavailable';
+      return queue;
+    }
+    requireTeamCapabilityOrDegrade('postgres-queue', true, env, { cwd: rootDir });
+    return new PostgresIntakeQueue({
+      sql,
+      project: opts.project ?? resolveProject(rootDir, env),
+      tenantId,
+      queueName: opts.queueName ?? env?.[INTAKE_QUEUE_NAME_ENV_KEY] ?? 'intake',
+      leaseSeconds: opts.leaseSeconds ?? env?.[INTAKE_QUEUE_LEASE_SECONDS_ENV_KEY],
+    });
+  }
+
+  // A registered kind:'queue' provider was selected but no in-tree instantiation
+  // path exists yet. The selection is honest — it names the resolved provider
+  // rather than silently downgrading to git.
+
+  throw new Error(
+    `Queue backend '${resolved.backend}' resolves to registered kind:'queue' provider ` +
+    `'${resolved.provider?.id}' but no in-tree instantiation path is wired yet.`,
+  );
 }