kenaz 0.3.11 → 0.3.12

package/core/.collaboration/core/task-api.js

@@ -216,6 +216,9 @@ function getTaskSync() {
   return _taskSync;
 }
 
+// TASK_2421: shared-room card replicas (relay) -- pure helper module, safe to require eagerly.
+const taskReplica = require('./task-replica');
+
 // TASK_2142 R2: Task Pool status push (lazy loaded, graceful degradation --
 // a sub-project checkout without .formation/ must not break moveTask).
 // Overridable via setPoolStatusPush() so tests can inject a fake/spy
@@ -487,6 +490,11 @@ function emitEmptyListDiagnostics(tasksDir) {
   } catch { /* never break list */ }
 }
 
+/** TASK_2421: is this api's project in an active shared room (relay-leased ids)? */
+function taskReplicaIsShared(api) {
+  return taskReplica.isSharedRoom(api._loadYggdrasilConfigSync());
+}
+
 class TaskAPI {
   /**
    * @param {Object} config
@@ -1568,6 +1576,14 @@ class TaskAPI {
     // { level_1: string[], level_2: [{endpoint, method, expect}], level_3: {scenario, generates} }
     if (taskData.verification) task.verification = taskData.verification;
     if (idAllocStamp) task.id_alloc = idAllocStamp;
+    // TASK_2421: plan-document id (e.g. 791-17) that maps onto this TASK id
+    if (taskData.alias && String(taskData.alias).trim()) {
+      task.alias = String(taskData.alias).trim();
+      const dup = await this._findAliasOwner(task.alias);
+      if (dup) console.warn(`⚠️  alias "${task.alias}" is already used by ${dup} -- alias lookups resolve to the first match`);
+    }
+    const replicaCtx = this._replicaCtx();
+    if (replicaCtx) task.shared_replica = true; // marker: later status changes keep the relay replica current
 
     // TASK_1110: parallel scope overlap warning (non-blocking).
     // When two tasks declare overlapping scope_paths / file references in
@@ -1604,16 +1620,146 @@ class TaskAPI {
     task._file_path = filePath;
     task._status_dir = 'backlog';
 
+    // TASK_2421: id came from the local counter inside a shared room -> loud warning.
+    if (idAllocStamp && taskReplicaIsShared(this)) {
+      const w = `${taskId} was allocated locally because the relay is unreachable -- this id may collide with one allocated by another node in the shared room. Re-check before pushing, and rename the card if another node reports the same id.`;
+      task.warnings = [...(task.warnings || []), w];
+      console.warn(`⚠️  ID COLLISION RISK: ${w}`);
+    }
+
+    // TASK_2421: publish a read-only replica to the shared room (best-effort).
+    if (replicaCtx) {
+      const r = await taskReplica.publishReplica(replicaCtx, task, 'backlog');
+      task.replica_published = r.ok;
+      if (!r.ok) {
+        const w = `card replica not published to the shared room (${r.error}); other nodes cannot read ${taskId} until a later update re-publishes it`;
+        task.warnings = [...(task.warnings || []), w];
+        console.warn(`⚠️  ${w}`);
+      }
+    }
+
     return task;
   }
 
+  // ---- TASK_2421: shared-room replicas, alias, import ----
+
+  /** Context for relay replica publishing, or null when not in a shared room / opted out. */
+  _replicaCtx() {
+    const yggConfig = this._loadYggdrasilConfigSync();
+    if (!taskReplica.shouldShareCards(yggConfig)) return null;
+    return this._buildReplicaCtx(yggConfig);
+  }
+
+  /** Read-side context: any shared room (share_cards only gates publishing). */
+  _replicaReadCtx() {
+    const yggConfig = this._loadYggdrasilConfigSync();
+    if (!taskReplica.isSharedRoom(yggConfig)) return null;
+    return this._buildReplicaCtx(yggConfig);
+  }
+
+  _buildReplicaCtx(yggConfig) {
+    return {
+      yggConfig,
+      key: this._readPublishableKey(),
+      projectRoot: this._resolveProjectRoot(),
+      node: taskReplica.nodeOf(yggConfig, this._getGitUser().name),
+      toYAML,
+    };
+  }
+
+  /** Keep the relay replica current (status + content). Never throws. */
+  async _syncReplica(task, statusDir) {
+    try {
+      if (!task || !task.shared_replica) return;
+      const ctx = this._replicaCtx();
+      if (!ctx) return;
+      const r = await taskReplica.syncReplica(ctx, task, statusDir);
+      // Row missing (create-time publish failed, or retention removed it): re-publish.
+      if (!r.ok) await taskReplica.publishReplica(ctx, task, statusDir || task._status_dir || 'backlog');
+    } catch { /* best-effort */ }
+  }
+
+  async _findAliasOwner(alias) {
+    try {
+      const want = String(alias).toLowerCase();
+      const all = await this.getAllTasks({ includeArchived: true });
+      const hit = all.tasks.find(t => t.alias && String(t.alias).toLowerCase() === want);
+      return hit ? hit.id : null;
+    } catch { return null; }
+  }
+
+  /** Map an alias (e.g. "791-17") to a TASK id; a TASK id or unknown input is returned unchanged. */
+  async resolveTaskRef(ref) {
+    if (!ref || this.validateTaskID(ref)) return ref;
+    return (await this._findAliasOwner(ref)) || ref;
+  }
+
+  /** Relay lookup by id or alias. Returns {found, row, replica}; never throws. */
+  async lookupReplica(ref) {
+    const ctx = this._replicaReadCtx();
+    if (!ctx) return { found: false };
+    return taskReplica.fetchReplica(ctx, ref, parseYAML);
+  }
+
+  /** Error for a command on an id missing locally; names the replica owner when the relay has the card. */
+  async _missingTaskError(taskId) {
+    const r = await this.lookupReplica(taskId);
+    if (r.found) {
+      const e = new Error(`任務不存在於本機: ${taskId} -- ${taskReplica.replicaNotice(taskId, r.row, r.replica)}. ` +
+        `This node cannot modify the owner's card.`);
+      e.replica = r;
+      return e;
+    }
+    return new Error(`任務不存在: ${taskId}`);
+  }
+
+  /** Import a relay replica as a local card marked with its origin node. */
+  async pullTask(taskId) {
+    await this._ensureStatusDirs();
+    const local = await this.getTask(taskId).catch(() => null);
+    if (local) throw new Error(`${taskId} already exists locally (${local._file_path}); nothing to import`);
+    const r = await this.lookupReplica(taskId);
+    if (!r.found) {
+      throw new Error(r.error ? `relay lookup failed: ${r.error}` : `任務不存在: ${taskId} (not among this shared room's replicas either)`);
+    }
+    const rep = r.replica || {};
+    const gitUser = this._getGitUser();
+    const origin = rep.origin_node || (r.row && r.row.created_by) || 'unknown';
+    const card = {
+      id: r.row.task_id,
+      hash: randomUUID(),
+      title: rep.title || r.row.title || '未命名任務',
+      description: rep.description || r.row.description || '',
+      priority: rep.priority || r.row.priority || 'P2',
+      status: 'pending',
+      role: rep.role || 'developer',
+      tags: [],
+      dependencies: [],
+      scope_paths: [],
+      requirements: toTextArray(rep.requirements),
+      acceptance_criteria: toTextArray(rep.acceptance_criteria),
+      technical_notes: [],
+      created_by: rep.created_by || { name: origin, git_user: origin, timestamp: new Date().toISOString() },
+      executed_by: null,
+      origin_node: origin,
+      imported_from_replica: { relay_status: r.row.status, imported_by: gitUser.name, imported_at: new Date().toISOString() },
+    };
+    if (rep.alias) card.alias = rep.alias;
+    const filePath = path.join(this.tasksDir, 'backlog', `${card.id}_${gitUser.git_user}.yaml`);
+    await fs.writeFile(filePath, toYAML(card));
+    await this._verifyPersisted(filePath, card);
+    card._file_path = filePath;
+    card._status_dir = 'backlog';
+    return card;
+  }
+
   /**
    * 更新任務
    */
   async updateTask(taskId, updates) {
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error(`任務不存在: ${taskId}`);
+      throw await this._missingTaskError(taskId);
     }
 
     // TASK_1771: coerce array-typed fields so a raw-string update can never
@@ -1667,6 +1813,8 @@ class TaskAPI {
     // 垃圾值只污染回傳值，不落 YAML（toYAML 過濾底線鍵 + 寫檔前已 delete）。
     updatedTask._status_dir = this._resolveStatusDirName(filePath);
 
+    await this._syncReplica(updatedTask, undefined); // TASK_2421: content refresh (title/alias/...)
+
     return updatedTask;
   }
 
@@ -1682,7 +1830,7 @@ class TaskAPI {
     if (!task) {
       task = await this.getTask(taskId);
       if (!task) {
-        throw new Error(`任務不存在: ${taskId}`);
+        throw await this._missingTaskError(taskId);
       }
     }
 
@@ -1844,6 +1992,9 @@ class TaskAPI {
       projectPath: this.projectPath,
     }).catch(() => {});
 
+    // TASK_2421: keep the shared-room replica's status current (best-effort, bounded by the relay timeout).
+    await this._syncReplica(updatedTask, targetDir);
+
     return updatedTask;
   }
 
@@ -1874,7 +2025,7 @@ class TaskAPI {
 
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error('任務不存在: ' + taskId);
+      throw await this._missingTaskError(taskId);
     }
 
     // M1: acquire claim marker (wx atomic — no TOCTOU)
@@ -1975,7 +2126,7 @@ class TaskAPI {
 
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error(`任務不存在: ${taskId}`);
+      throw await this._missingTaskError(taskId);
     }
 
     // TASK_2233: backlog → done is not an allowed transition; say what to do instead
@@ -2016,6 +2167,7 @@ class TaskAPI {
     }
 
     const postCompleteRuns = !options.skipPostComplete;
+    let postCompleteSummary = null;
     const result = await this.moveTask(taskId, 'done', updatedTask);
 
     try {
@@ -2040,7 +2192,7 @@ class TaskAPI {
       try {
         const { postComplete } = require('../../.formation/tools/post-complete.js');
         console.log(`\n🔗 自動執行 post-complete for ${taskId}...\n`);
-        await postComplete({
+        const pc = await postComplete({
           taskId,
           keep: options.keep || 10,
           skipArchive: options.skipArchive || false,
@@ -2048,13 +2200,19 @@ class TaskAPI {
           dryRun: options.dryRun || false,
           message: options.message,
           projectPath: this.projectPath,
+          noSource: options.noSource || false,
         });
+        postCompleteSummary = (pc && pc.summary) || null;
       } catch (error) {
         console.error(`⚠️  post-complete 失敗: ${error.message}`);
-        console.error('   任務已完成，但 post-complete 需要手動執行');
+        // TASK_2420: surface the failure to the caller instead of a bare "completed".
+        postCompleteSummary = { outcome: 'not_completed', cardState: 'done_unreconciled', warnings: [],
+          steps: [{ step: 'post_complete', status: 'failed', reason: error.message }] };
       }
     }
 
+    // TASK_2420: non-enumerable so it never leaks into YAML / JSON serialisation of the task.
+    Object.defineProperty(result, 'postComplete', { value: postCompleteSummary, enumerable: false });
     return result;
   }
 
@@ -2111,7 +2269,8 @@ class TaskAPI {
         const desc = (t.description || '').toLowerCase();
         const id = (t.id || '').toLowerCase();
         const tags = (t.tags || []).join(' ').toLowerCase();
-        return title.includes(searchLower) || desc.includes(searchLower) || id.includes(searchLower) || tags.includes(searchLower);
+        const alias = String(t.alias || '').toLowerCase(); // TASK_2421
+        return title.includes(searchLower) || desc.includes(searchLower) || id.includes(searchLower) || tags.includes(searchLower) || (alias !== '' && alias.includes(searchLower));
       });
     }
 
@@ -2488,6 +2647,7 @@ Commands:
   node task-api.js update TASK_ID [--title T] [--description D] [--priority P] [--role R] [--technical-notes N]...
     陣列欄位（tags/dependencies/scope-paths/requirements/acceptance-criteria/technical-notes 等）
     預設為整組取代（會回顯被移除的既有項目）；加 --append 改為追加到既有項目之後（與既有重複的項目會略過並回顯）
+  node task-api.js pull TASK_ID                 匯入共享 room 的唯讀 replica 為本機卡片（標記 origin_node；TASK_2421）
   node task-api.js claim TASK_ID
   node task-api.js complete TASK_ID [--actual-hours HOURS]
   node task-api.js reconcile [--remote origin] [--base main] [--apply] [--worktrees]   關閉分支已併入 base 的 active 任務（預設 dry-run）
@@ -2541,6 +2701,7 @@ Create 選項:
   --args-file PATH         UTF-8 JSON 物件；支援 camelCase / snake_case，CLI 旗標優先
                            requirements / acceptance_criteria / technical_notes 使用 JSON 陣列
                            一般品質門檻：requirements >= 3，acceptance_criteria >= 3，technical_notes >= 2
+  --alias PLAN_ID          計畫文件編號（如 791-17），get/update/move/complete/search 皆可用（TASK_2421）
   --estimated-hours N      預估工時（小時）
   --branch NAME            Git 分支
   --notes TEXT             備註
@@ -2577,6 +2738,11 @@ Create 選項:
 
       const command = args[0];
 
+      // TASK_2421: a plan-document alias (e.g. 791-17) works anywhere a TASK id does.
+      if (['get', 'update', 'move', 'complete', 'claim', 'pull'].includes(command) && args[1] && !args[1].startsWith('--')) {
+        args[1] = await api.resolveTaskRef(args[1]);
+      }
+
       if (command === 'reconcile') {
         // TASK_2404: close active cards whose branches already landed on <remote>/<base>
         const argOf = (n, d) => { const i = args.indexOf(n); return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : d; };
@@ -2846,14 +3012,32 @@ Create 選項:
           console.error('錯誤: 缺少任務 ID');
           process.exit(1);
         }
-        const task = await api.getTask(taskId);
+        // TASK_2421: a non-TASK ref (relay-only alias) skips the local lookup (getTask throws on it)
+        const task = api.validateTaskID(taskId) ? await api.getTask(taskId) : null;
         if (task) {
           console.log(JSON.stringify(task, null, 2));
         } else {
-          console.error(`任務不存在: ${taskId}`);
-          process.exit(1);
+          // TASK_2421: id unknown locally -> look for a read-only replica in the shared room
+          const rep = await api.lookupReplica(taskId);
+          if (rep.found) {
+            const out = { ...rep.replica, id: rep.row.task_id, relay_status: rep.row.status, read_only_replica: true,
+              replica_notice: require('./task-replica').replicaNotice(taskId, rep.row, rep.replica) };
+            console.log(JSON.stringify(out, null, 2));
+            console.error(`ℹ️  ${taskId}: ${out.replica_notice}`);
+          } else {
+            console.error(`任務不存在: ${taskId}`);
+            if (rep.error) console.error(`   (shared-room replica lookup failed: ${rep.error})`);
+            process.exit(1);
+          }
         }
 
+      } else if (command === 'pull') {
+        // TASK_2421: import a shared-room replica as a local card marked with its origin node
+        const taskId = args[1];
+        if (!taskId) { console.error('錯誤: 缺少任務 ID'); process.exit(1); }
+        const card = await api.pullTask(taskId);
+        console.log(`✅ 已匯入: ${card.id} (origin node: ${card.origin_node}) -> ${card._file_path}`);
+
       } else if (command === 'create') {
         // TASK_1599: Windows CreateProcess caps command line at 32767 UTF-16 chars.
         // Detailed task cards (long description + many requirements) easily exceed this
@@ -2951,6 +3135,7 @@ Create 選項:
           // is the documented flag name; it maps onto the pre-existing `source`
           // field that createTask() already promotes onto the task when truthy.
           source: getArg('--source') || getArg('--origin') || fromFile('source') || fromFile('origin') || null,
+          alias: getArg('--alias') || fromFile('alias') || undefined, // TASK_2421
         };
 
         const reqs = getMulti('--requirements');
@@ -2987,6 +3172,9 @@ Create 選項:
         if (task.scope_paths && task.scope_paths.length > 0) console.log(`範圍: ${task.scope_paths.join(', ')}`);
         if (task.estimated_hours != null) console.log(`預估工時: ${task.estimated_hours}h`);
         if (task.branch) console.log(`分支: ${task.branch}`);
+        if (task.alias) console.log(`別名: ${task.alias}`);
+        if (task.replica_published) console.log(`共享: replica published to the shared room (read-only for other nodes)`);
+        for (const w of task.warnings || []) console.log(`⚠️  ${w}`);
 
       } else if (command === 'claim') {
         const taskId = args[1];
@@ -3021,9 +3209,29 @@ Create 選項:
         if (args.includes('--skip-post-complete')) {
           options.skipPostComplete = true;
         }
+        // TASK_2420: runtime/config tasks with no branch — git merge/verify reported as skipped
+        if (args.includes('--no-source')) {
+          options.noSource = true;
+        }
         const task = await api.completeTask(taskId, options);
-        console.log(`✅ 任務已完成: ${task.id}`);
-        if (task.actual_hours != null) console.log(`實際工時: ${task.actual_hours} 小時`);
+        const pcs = task.postComplete;
+        const stepLines = pcs ? (pcs.steps || []).map(st => `  ${st.status === 'failed' ? '❌' : st.status === 'skipped' ? '⏭' : '✅'} ${st.step}: ${st.status}${st.reason ? ' — ' + st.reason : ''}`) : [];
+        if (pcs && pcs.outcome === 'not_completed') {
+          // The card was NOT delivered: say so, with the real cause, and fail the command.
+          console.error(`❌ 任務未完成: ${task.id} — ${pcs.cardState === 'blocked' ? '已移至 blocked/' : pcs.cardState === 'active' ? '留在 active/' : '卡片仍在 done/ 但交付失敗（需人工處理）'}`);
+          for (const l of stepLines) console.error(l);
+          console.error(`  若此任務沒有 source 變更（runtime/config 修復），請改用: complete ${task.id} --no-source`);
+          process.exitCode = 1;
+        } else {
+          console.log(`✅ 任務已完成${pcs && pcs.outcome === 'completed_with_warnings' ? '（含警告）' : ''}: ${task.id}`);
+          if (pcs && pcs.outcome === 'completed_with_warnings') {
+            for (const l of stepLines) console.log(l);
+            for (const w of pcs.warnings) console.log(`  ⚠️  ${w}`);
+          } else {
+            for (const l of stepLines.filter(l => l.includes('⏭'))) console.log(l);
+          }
+          if (task.actual_hours != null) console.log(`實際工時: ${task.actual_hours} 小時`);
+        }
 
       } else if (command === 'move') {
         const taskId = args[1];
@@ -3374,6 +3582,7 @@ Create 選項:
         const reqs = getMulti('--requirements'); if (reqs) updates.requirements = reqs;
         const ac = getMulti('--acceptance-criteria'); if (ac) updates.acceptance_criteria = ac;
         const tn = getMulti('--technical-notes'); if (tn) updates.technical_notes = tn;
+        const aliasArg = getArg('--alias'); if (aliasArg !== null) updates.alias = aliasArg; // TASK_2421
         const mergeLandedArg = getArg('--merge-landed');
         if (mergeLandedArg !== null) updates.merge_landed = (mergeLandedArg === 'true');
 

package/core/.collaboration/core/task-replica.js

@@ -0,0 +1,189 @@
+'use strict';
+/**
+ * task-replica.js (TASK_2421)
+ *
+ * Shared-room card replicas. Task IDs are allocated room-wide via relay leases
+ * but card files live only on the creating node (.kenaz/tasks is gitignored), so
+ * other nodes got "任務不存在" for ids they saw in git/messages. When the project
+ * is in an active shared room, `task-api create` also publishes a READ-ONLY
+ * replica of the card to the relay tasks table, and `get/update/move/complete`
+ * on an unknown id look that replica up.
+ *
+ * Why status 'assigned' with NO assigned_to (no relay change needed):
+ *   - GET /api/tasks defaults to status=pool, so the pool list never shows it
+ *   - kenaz_pool_pull (inbox) filters assigned_to == this node, so the creator's
+ *     own inbox does not fill with replicas either
+ *   - 'assigned' is already a valid, non-pool relay status
+ *   Residual: relay claim is not status-gated, so an explicit claim by exact id
+ *   would still succeed; replicas are documented as non-claimable (full_yaml
+ *   carries `replica: true`).
+ *
+ * Everything here is best-effort and never throws into a caller: a relay problem
+ * must never fail a local create/move.
+ */
+
+const http = require('http');
+const https = require('https');
+const path = require('path');
+
+const TIMEOUT_MS = 3000;
+// local status dir -> relay status. Backlog/pending stays the non-pool 'assigned'.
+const RELAY_STATUS = {
+  backlog: 'assigned', pending: 'assigned',
+  active: 'in_progress', blocked: 'blocked', done: 'done', cancel: 'cancelled',
+};
+const ALL_STATUSES = 'assigned,in_progress,blocked,done,cancelled,completed,claimed,pool';
+
+/** Shared-room condition, identical to generateTaskID's. */
+function isSharedRoom(yggConfig) {
+  return !!(yggConfig && yggConfig.enabled !== false &&
+    yggConfig.relay_url && String(yggConfig.relay_url).trim() !== '' &&
+    yggConfig.shared_task_ids !== false);
+}
+
+/** Replica publishing: shared room AND not opted out (`share_cards: false`). */
+function shouldShareCards(yggConfig) {
+  return isSharedRoom(yggConfig) && yggConfig.share_cards !== false;
+}
+
+function projectOf(yggConfig, projectRoot) {
+  return (yggConfig.yggdrasil_project && String(yggConfig.yggdrasil_project).trim()) ||
+    path.basename(projectRoot) || 'default';
+}
+
+function nodeOf(yggConfig, gitUserName) {
+  return (yggConfig.node_name && String(yggConfig.node_name).trim()) || gitUserName || 'unknown';
+}
+
+function relayRequest(yggConfig, key, method, pathAndQuery, bodyObj) {
+  return new Promise((resolve, reject) => {
+    const base = String(yggConfig.relay_url).replace(/^wss:\/\//, 'https://').replace(/^ws:\/\//, 'http://');
+    let url;
+    try { url = new URL(pathAndQuery, base); } catch { reject(new Error('invalid relay_url')); return; }
+    const isHttps = url.protocol === 'https:';
+    const body = bodyObj !== undefined ? JSON.stringify(bodyObj) : null;
+    let settled = false;
+    const req = (isHttps ? https : http).request({
+      hostname: url.hostname, port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search, method,
+      headers: {
+        ...(body ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } : {}),
+        ...(key ? { Authorization: `Bearer ${key}` } : {}),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => {
+        if (settled) return; settled = true;
+        if (res.statusCode < 200 || res.statusCode >= 300) { reject(new Error(`relay HTTP ${res.statusCode}`)); return; }
+        try { resolve(data ? JSON.parse(data) : null); } catch (e) { reject(new Error(`relay parse error: ${e.message}`)); }
+      });
+    });
+    req.on('error', (e) => { if (!settled) { settled = true; reject(e); } });
+    const timer = setTimeout(() => { if (!settled) { settled = true; req.destroy(); reject(new Error('relay timeout')); } }, TIMEOUT_MS);
+    req.on('close', () => clearTimeout(timer));
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+/** Plain-object copy of the card without internal `_` keys. */
+function cleanCard(task) {
+  const out = {};
+  for (const [k, v] of Object.entries(task || {})) if (!k.startsWith('_')) out[k] = v;
+  return out;
+}
+
+/**
+ * Publish a replica. ctx = { yggConfig, key, projectRoot, node, toYAML }.
+ * Returns {ok:true} | {ok:false, error}.
+ */
+async function publishReplica(ctx, task, localStatusDir) {
+  try {
+    const card = cleanCard(task);
+    const replicaCard = {
+      replica: true,
+      origin_node: ctx.node,
+      id: card.id, title: card.title, description: card.description,
+      priority: card.priority, status: card.status, alias: card.alias || null,
+      requirements: card.requirements || [], acceptance_criteria: card.acceptance_criteria || [],
+      created_by: card.created_by || null,
+    };
+    await relayRequest(ctx.yggConfig, ctx.key, 'POST', '/api/tasks', {
+      task_id: task.id,
+      project: projectOf(ctx.yggConfig, ctx.projectRoot),
+      status: RELAY_STATUS[localStatusDir || 'backlog'] || 'assigned',
+      priority: card.priority || 'P2',
+      title: card.title,
+      description: card.description,
+      created_by: ctx.node,
+      full_yaml: ctx.toYAML(replicaCard),
+    });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/** Push a status (and refreshed card) to an existing replica row. */
+async function syncReplica(ctx, task, localStatusDir) {
+  try {
+    const card = cleanCard(task);
+    const body = {
+      project: projectOf(ctx.yggConfig, ctx.projectRoot),
+      title: card.title, description: card.description, priority: card.priority,
+      full_yaml: ctx.toYAML({
+        replica: true, origin_node: ctx.node, id: card.id, title: card.title,
+        description: card.description, priority: card.priority, status: card.status,
+        alias: card.alias || null, requirements: card.requirements || [],
+        acceptance_criteria: card.acceptance_criteria || [], created_by: card.created_by || null,
+      }),
+    };
+    if (localStatusDir && RELAY_STATUS[localStatusDir]) body.status = RELAY_STATUS[localStatusDir];
+    await relayRequest(ctx.yggConfig, ctx.key, 'PATCH',
+      `/api/tasks/${encodeURIComponent(task.id)}?project=${encodeURIComponent(body.project)}`, body);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Look a card up on the relay by TASK id or alias. Returns
+ * { found:true, row, replica } | { found:false } | { found:false, error }.
+ * `replica` is the parsed full_yaml (or a minimal object from row columns).
+ */
+async function fetchReplica(ctx, idOrAlias, parseYAML) {
+  try {
+    const project = projectOf(ctx.yggConfig, ctx.projectRoot);
+    const rows = await relayRequest(ctx.yggConfig, ctx.key, 'GET',
+      `/api/tasks?project=${encodeURIComponent(project)}&status=${ALL_STATUSES}&limit=1000&include_blocked=1`);
+    const list = Array.isArray(rows) ? rows : [];
+    const want = String(idOrAlias).toLowerCase();
+    for (const row of list) {
+      let card = null;
+      try { card = row.full_yaml ? parseYAML(row.full_yaml) : null; } catch { card = null; }
+      const alias = card && card.alias ? String(card.alias).toLowerCase() : null;
+      if (String(row.task_id).toLowerCase() === want || (alias && alias === want)) {
+        return { found: true, row, replica: card && Object.keys(card).length ? card : {
+          id: row.task_id, title: row.title, description: row.description, priority: row.priority,
+        } };
+      }
+    }
+    return { found: false };
+  } catch (e) {
+    return { found: false, error: e.message };
+  }
+}
+
+/** Human-readable "read-only replica" notice. */
+function replicaNotice(taskId, row, replica) {
+  const node = (replica && replica.origin_node) || (row && row.created_by) || 'unknown';
+  return `read-only replica; card lives on node ${node}. ` +
+    `To track it locally: node .collaboration/core/task-api.js pull ${taskId}`;
+}
+
+module.exports = {
+  isSharedRoom, shouldShareCards, projectOf, nodeOf, relayRequest,
+  publishReplica, syncReplica, fetchReplica, replicaNotice, RELAY_STATUS,
+};

package/core/.formation/.merge-lock

@@ -0,0 +1 @@
+{"pid":32452,"taskId":"TASK_2356","acquiredAt":"2026-10-09T10:19:19.033Z"}

package/core/.formation/bifrost/codex-doctor.js

@@ -127,10 +127,20 @@ function diagnose() {
   if (unreg.length) notes.push('Kenaz hooks not registered for: ' + unreg.join(', ') + '. Run: node .formation/bifrost/setup-codex.js');
   if (untrusted.length) notes.push('Kenaz hooks registered but NOT trusted (' + untrusted.join(', ') + '); codex does not run them. Open codex, type /hooks, and trust the kenaz entries (re-trust after any change to the hook command).');
   if (trust.UserPromptSubmit.registered && !trust.UserPromptSubmit.pull) notes.push('UserPromptSubmit hook lacks --pull, so independently opened codex sessions receive no peer mail. Remove the kenaz hook blocks from config.toml and re-run setup-codex.js.');
-  return { trust, delivery_mode: deliveryMode(trust), ok: notes.length === 0, notes };
+  const managed = managedDaemon();
+  const mode = deliveryMode(trust);
+  if (managed && mode === 'pull-on-prompt') notes.push(MANAGED_NOTE);
+  return { trust, delivery_mode: mode, managed_daemon: managed, ok: notes.filter((n) => n !== MANAGED_NOTE).length === 0, notes };
 }
 
-module.exports = { promptText, skillText, installPrompts, installAgentsBlock, removeAgentsBlock, agentsBlock, hookTrust, deliveryMode, diagnose, SHIM_REL, EVENTS };
+// TASK_2419: Codex desktop managed app-server daemon (unix control socket / pid file under CODEX_HOME).
+function managedDaemon(home) {
+  const h = home || codexHome();
+  return fs.existsSync(path.join(h, 'app-server-control', 'app-server-control.sock')) || fs.existsSync(path.join(h, 'app-server-daemon', 'daemon.pid'));
+}
+const MANAGED_NOTE = 'Codex managed daemon detected: Kenaz has no push channel into it. Peer mail arrives on your next prompt via the UserPromptSubmit --pull hook (delivery_mode pull-on-prompt).';
+
+module.exports = { managedDaemon, MANAGED_NOTE, promptText, skillText, installPrompts, installAgentsBlock, removeAgentsBlock, agentsBlock, hookTrust, deliveryMode, diagnose, SHIM_REL, EVENTS };
 
 if (require.main === module) {
   if (process.argv.includes('--install-prompts')) console.log(JSON.stringify(installPrompts()));

package/core/.formation/bifrost/codex-doctor.test.js

@@ -67,3 +67,18 @@ test('global AGENTS.md gets one managed Kenaz block (wish / field report guidanc
   assert.doesNotMatch(after, /kenaz:begin|kenaz_wish_create/);
   delete process.env.CODEX_HOME;
 });
+
+test('TASK_2419: managed daemon detected from CODEX_HOME markers; diagnose reports it without failing ok', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cx-md-'));
+  assert.strictEqual(D.managedDaemon(home), false); // control: empty home
+  fs.mkdirSync(path.join(home, 'app-server-control'));
+  fs.writeFileSync(path.join(home, 'app-server-control', 'app-server-control.sock'), '');
+  assert.strictEqual(D.managedDaemon(home), true);
+  process.env.CODEX_HOME = home;
+  fs.writeFileSync(path.join(home, 'config.toml'), cfg(true, true));
+  const d = D.diagnose();
+  assert.strictEqual(d.managed_daemon, true);
+  assert.strictEqual(d.delivery_mode, 'pull-on-prompt');
+  assert.ok(d.notes.includes(D.MANAGED_NOTE)); assert.strictEqual(d.ok, d.notes.length === 1); // the managed note alone is informational
+  delete process.env.CODEX_HOME;
+});