feat: Implement team artifacts feature with tree navigation and file preview

2026-02-28 09:23:08 +08:00 · 2026-02-15 18:14:07 +08:00
parent 0d56396710
commit 4ddd2e9f17
26 changed files with 1250 additions and 3038 deletions
--- a/ccw/src/core/routes/team-routes.ts
+++ b/ccw/src/core/routes/team-routes.ts
@@ -1,82 +1,346 @@
 /**
 * Team Routes - REST API for team message visualization & management
 *
+ * Directory Structure (NEW - session-bound):
+ * .workflow/.team/
+ * ├── TLS-demo-2026-02-15/      # session-id (root)
+ * │   ├── .msg/                 # messages (session-level)
+ * │   │   ├── meta.json
+ * │   │   └── messages.jsonl
+ * │   ├── spec/                 # artifacts (siblings of .msg)
+ * │   └── plan/
+ *
+ * Legacy Support: Also scans .workflow/.team-msg/{team-name}/
+ *
 * Endpoints:
- * - GET    /api/teams                    - List all teams (with ?location filter)
- * - GET    /api/teams/:name/messages     - Get messages (with filters)
- * - GET    /api/teams/:name/status       - Get member status summary
- * - POST   /api/teams/:name/archive      - Archive a team
- * - POST   /api/teams/:name/unarchive    - Unarchive a team
- * - DELETE  /api/teams/:name              - Delete a team
+ * - GET    /api/teams                       - List all teams (with ?location filter)
+ * - GET    /api/teams/:name/messages        - Get messages (with filters)
+ * - GET    /api/teams/:name/status          - Get member status summary
+ * - GET    /api/teams/:name/artifacts       - Get artifacts tree structure
+ * - GET    /api/teams/:name/artifacts/*path - Get artifact file content
+ * - POST   /api/teams/:name/archive         - Archive a team
+ * - POST   /api/teams/:name/unarchive       - Unarchive a team
+ * - DELETE /api/teams/:name                 - Delete a team
 */

-import { existsSync, readdirSync, rmSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readdirSync, rmSync, statSync, readFileSync } from 'fs';
+import { join, extname } from 'path';
 import type { RouteContext } from './types.js';
 import { readAllMessages, getLogDir, getEffectiveTeamMeta, readTeamMeta, writeTeamMeta } from '../../tools/team-msg.js';
 import type { TeamMeta } from '../../tools/team-msg.js';
 import { getProjectRoot } from '../../utils/path-validator.js';

+/**
+ * Artifact node structure for tree representation
+ */
+interface ArtifactNode {
+  type: 'file' | 'directory';
+  name: string;
+  path: string;           // Relative to session directory
+  contentType: 'markdown' | 'json' | 'text' | 'unknown';
+  size?: number;          // File size (bytes)
+  modifiedAt?: string;    // Last modified time
+  children?: ArtifactNode[];  // Directory children
+}
+
+/**
+ * Detect content type from file extension
+ */
+function detectContentType(fileName: string): ArtifactNode['contentType'] {
+  const ext = extname(fileName).toLowerCase();
+  if (['.md', '.markdown'].includes(ext)) return 'markdown';
+  if (['.json'].includes(ext)) return 'json';
+  if (['.txt', '.log', '.tsv', '.csv'].includes(ext)) return 'text';
+  return 'unknown';
+}
+
+/**
+ * Recursively scan artifacts directory
+ * Skips .msg directory (message storage)
+ */
+function scanArtifactsDirectory(dirPath: string, basePath: string): ArtifactNode[] {
+  const nodes: ArtifactNode[] = [];
+
+  if (!existsSync(dirPath)) {
+    return nodes;
+  }
+
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip .msg directory - that's for messages, not artifacts
+      if (entry.name === '.msg') continue;
+
+      const fullPath = join(dirPath, entry.name);
+      const relativePath = join(basePath, entry.name).replace(/\\/g, '/');
+
+      if (entry.isDirectory()) {
+        const children = scanArtifactsDirectory(fullPath, relativePath);
+        const stat = statSync(fullPath);
+
+        nodes.push({
+          type: 'directory',
+          name: entry.name,
+          path: relativePath,
+          contentType: 'unknown',
+          modifiedAt: stat.mtime.toISOString(),
+          children,
+        });
+      } else if (entry.isFile()) {
+        const stat = statSync(fullPath);
+
+        nodes.push({
+          type: 'file',
+          name: entry.name,
+          path: relativePath,
+          contentType: detectContentType(entry.name),
+          size: stat.size,
+          modifiedAt: stat.mtime.toISOString(),
+        });
+      }
+    }
+
+    // Sort: directories first, then files, both alphabetically
+    nodes.sort((a, b) => {
+      if (a.type !== b.type) {
+        return a.type === 'directory' ? -1 : 1;
+      }
+      return a.name.localeCompare(b.name);
+    });
+  } catch (e) {
+    // Ignore errors (permission, etc.)
+  }
+
+  return nodes;
+}
+
+/**
+ * Get session directory (artifacts are siblings of .msg/)
+ * NEW: .workflow/.team/{session-id}/
+ */
+function getSessionDir(sessionId: string, root: string): string {
+  return join(root, '.workflow', '.team', sessionId);
+}
+
+/**
+ * Get legacy team directory
+ * OLD: .workflow/.team-msg/{team-name}/
+ */
+function getLegacyTeamDir(teamName: string, root: string): string {
+  return join(root, '.workflow', '.team-msg', teamName);
+}
+
+/**
+ * List all sessions from new .team/ directory
+ * Each subdirectory with .msg/ folder is a valid session
+ */
+function listSessions(root: string): Array<{ sessionId: string; path: string }> {
+  const teamDir = join(root, '.workflow', '.team');
+  const sessions: Array<{ sessionId: string; path: string }> = [];
+
+  console.log('[team-routes] listSessions - root:', root);
+  console.log('[team-routes] listSessions - teamDir:', teamDir);
+  console.log('[team-routes] listSessions - existsSync(teamDir):', existsSync(teamDir));
+
+  if (!existsSync(teamDir)) {
+    return sessions;
+  }
+
+  try {
+    const entries = readdirSync(teamDir, { withFileTypes: true });
+    console.log('[team-routes] listSessions - entries:', entries.map(e => e.name));
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const msgDir = join(teamDir, entry.name, '.msg');
+        console.log('[team-routes] listSessions - checking msgDir:', msgDir, 'exists:', existsSync(msgDir));
+        if (existsSync(msgDir)) {
+          sessions.push({ sessionId: entry.name, path: join(teamDir, entry.name) });
+        }
+      }
+    }
+  } catch (err) {
+    console.error('[team-routes] listSessions error:', err);
+  }
+
+  console.log('[team-routes] listSessions - found sessions:', sessions.length);
+  return sessions;
+}
+
+/**
+ * List teams from old .team-msg/ directory (backward compatibility)
+ */
+function listLegacyTeams(root: string): Array<{ teamName: string; path: string }> {
+  const teamMsgDir = join(root, '.workflow', '.team-msg');
+  const teams: Array<{ teamName: string; path: string }> = [];
+
+  if (!existsSync(teamMsgDir)) {
+    return teams;
+  }
+
+  try {
+    const entries = readdirSync(teamMsgDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        teams.push({ teamName: entry.name, path: join(teamMsgDir, entry.name) });
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return teams;
+}
+
 function jsonResponse(res: import('http').ServerResponse, status: number, data: unknown): void {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(data));
 }

+/**
+ * Resolve project root from context
+ * Priority: initialPath (from server startup) > getProjectRoot()
+ */
+function resolveProjectRoot(ctx: RouteContext): string {
+  return ctx.initialPath || getProjectRoot();
+}
+
 export async function handleTeamRoutes(ctx: RouteContext): Promise<boolean> {
  const { pathname, req, res, url, handlePostRequest } = ctx;

  if (!pathname.startsWith('/api/teams')) return false;

+  // ====== GET /api/teams/debug - Debug endpoint ======
+  if (pathname === '/api/teams/debug' && req.method === 'GET') {
+    const root = resolveProjectRoot(ctx);
+    const teamDir = join(root, '.workflow', '.team');
+    const legacyDir = join(root, '.workflow', '.team-msg');
+
+    const debug = {
+      projectRoot: root,
+      teamDir,
+      legacyDir,
+      teamDirExists: existsSync(teamDir),
+      legacyDirExists: existsSync(legacyDir),
+      teamDirContents: [] as string[],
+      sessionMsgDirs: [] as { session: string; msgExists: boolean }[],
+    };
+
+    if (existsSync(teamDir)) {
+      try {
+        const entries = readdirSync(teamDir, { withFileTypes: true });
+        debug.teamDirContents = entries.map(e => `${e.name} (${e.isDirectory() ? 'dir' : 'file'})`);
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const msgDir = join(teamDir, entry.name, '.msg');
+            debug.sessionMsgDirs.push({
+              session: entry.name,
+              msgExists: existsSync(msgDir),
+            });
+          }
+        }
+      } catch (err) {
+        (debug as any).error = String(err);
+      }
+    }
+
+    jsonResponse(res, 200, debug);
+    return true;
+  }
+
  // ====== GET /api/teams - List all teams ======
  if (pathname === '/api/teams' && req.method === 'GET') {
    try {
-      const root = getProjectRoot();
-      const teamMsgDir = join(root, '.workflow', '.team-msg');
+      const root = resolveProjectRoot(ctx);
+      const locationFilter = url.searchParams.get('location') || 'active';

-      if (!existsSync(teamMsgDir)) {
-        jsonResponse(res, 200, { teams: [] });
-        return true;
+      // Collect from new session-bound structure
+      const sessions = listSessions(root);
+      // Collect from legacy structure
+      const legacyTeams = listLegacyTeams(root);
+
+      // Build unified team list
+      const teams: Array<{
+        name: string;
+        messageCount: number;
+        lastActivity: string;
+        status: string;
+        created_at: string;
+        updated_at: string;
+        archived_at?: string;
+        pipeline_mode?: string;
+        memberCount: number;
+        members: string[];
+        isLegacy: boolean;
+      }> = [];
+
+      // Process new sessions
+      for (const session of sessions) {
+        const messages = readAllMessages(session.sessionId);
+        const lastMsg = messages[messages.length - 1];
+        const meta = getEffectiveTeamMeta(session.sessionId);
+
+        const memberSet = new Set<string>();
+        for (const msg of messages) {
+          memberSet.add(msg.from);
+          memberSet.add(msg.to);
+        }
+
+        teams.push({
+          name: session.sessionId,
+          messageCount: messages.length,
+          lastActivity: lastMsg?.ts || '',
+          status: meta.status,
+          created_at: meta.created_at,
+          updated_at: meta.updated_at,
+          archived_at: meta.archived_at,
+          pipeline_mode: meta.pipeline_mode,
+          memberCount: memberSet.size,
+          members: Array.from(memberSet),
+          isLegacy: false,
+        });
      }

-      const locationFilter = url.searchParams.get('location') || 'active';
-      const entries = readdirSync(teamMsgDir, { withFileTypes: true });
+      // Process legacy teams
+      for (const team of legacyTeams) {
+        // Skip if already found in new structure (same name)
+        if (teams.some(t => t.name === team.teamName)) continue;

-      const teams = entries
-        .filter(e => e.isDirectory())
-        .map(e => {
-          const messages = readAllMessages(e.name);
-          const lastMsg = messages[messages.length - 1];
-          const meta = getEffectiveTeamMeta(e.name);
+        const messages = readAllMessages(team.teamName);
+        const lastMsg = messages[messages.length - 1];
+        const meta = getEffectiveTeamMeta(team.teamName);

-          // Count unique members from messages
-          const memberSet = new Set<string>();
-          for (const msg of messages) {
-            memberSet.add(msg.from);
-            memberSet.add(msg.to);
-          }
+        const memberSet = new Set<string>();
+        for (const msg of messages) {
+          memberSet.add(msg.from);
+          memberSet.add(msg.to);
+        }

-          return {
-            name: e.name,
-            messageCount: messages.length,
-            lastActivity: lastMsg?.ts || '',
-            status: meta.status,
-            created_at: meta.created_at,
-            updated_at: meta.updated_at,
-            archived_at: meta.archived_at,
-            pipeline_mode: meta.pipeline_mode,
-            memberCount: memberSet.size,
-            members: Array.from(memberSet),
-          };
-        })
+        teams.push({
+          name: team.teamName,
+          messageCount: messages.length,
+          lastActivity: lastMsg?.ts || '',
+          status: meta.status,
+          created_at: meta.created_at,
+          updated_at: meta.updated_at,
+          archived_at: meta.archived_at,
+          pipeline_mode: meta.pipeline_mode,
+          memberCount: memberSet.size,
+          members: Array.from(memberSet),
+          isLegacy: true,
+        });
+      }
+
+      // Apply filters
+      const filteredTeams = teams
        .filter(t => {
          if (locationFilter === 'all') return true;
          if (locationFilter === 'archived') return t.status === 'archived';
-          // 'active' = everything that's not archived
          return t.status !== 'archived';
        })
        .sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));

-      jsonResponse(res, 200, { teams });
+      jsonResponse(res, 200, { teams: filteredTeams });
      return true;
    } catch (error) {
      jsonResponse(res, 500, { error: (error as Error).message });
@@ -126,14 +390,70 @@ export async function handleTeamRoutes(ctx: RouteContext): Promise<boolean> {
  const deleteMatch = pathname.match(/^\/api\/teams\/([^/]+)$/);
  if (deleteMatch && req.method === 'DELETE') {
    const teamName = decodeURIComponent(deleteMatch[1]);
+    const root = resolveProjectRoot(ctx);
    try {
-      const dir = getLogDir(teamName);
-      if (!existsSync(dir)) {
-        jsonResponse(res, 404, { error: `Team "${teamName}" not found` });
+      // Try new session-bound location first
+      const sessionDir = getSessionDir(teamName, root);
+      if (existsSync(sessionDir)) {
+        rmSync(sessionDir, { recursive: true, force: true });
+        jsonResponse(res, 200, { success: true, team: teamName, deleted: true });
        return true;
      }
-      rmSync(dir, { recursive: true, force: true });
-      jsonResponse(res, 200, { success: true, team: teamName, deleted: true });
+
+      // Fallback to legacy location
+      const legacyDir = getLegacyTeamDir(teamName, root);
+      if (existsSync(legacyDir)) {
+        rmSync(legacyDir, { recursive: true, force: true });
+        jsonResponse(res, 200, { success: true, team: teamName, deleted: true });
+        return true;
+      }
+
+      jsonResponse(res, 404, { error: `Team "${teamName}" not found` });
+      return true;
+    } catch (error) {
+      jsonResponse(res, 500, { error: (error as Error).message });
+      return true;
+    }
+  }
+
+  // ====== GET requests only from here ======
+  if (req.method !== 'GET') return false;
+
+  // ====== GET /api/teams/:name/artifacts or /api/teams/:name/artifacts/*path ======
+  const artifactsMatch = pathname.match(/^\/api\/teams\/([^/]+)\/artifacts(?:\/(.*))?$/);
+  if (artifactsMatch) {
+    const artifactsTeamName = decodeURIComponent(artifactsMatch[1]);
+    const artifactPath = artifactsMatch[2] ? decodeURIComponent(artifactsMatch[2]) : null;
+    const root = resolveProjectRoot(ctx);
+
+    try {
+      // NEW: Session directory contains both .msg/ and artifacts
+      // The team name IS the session ID now
+      const sessionDir = getSessionDir(artifactsTeamName, root);
+
+      if (!existsSync(sessionDir)) {
+        // Check if it's a legacy team with session_id
+        const meta = getEffectiveTeamMeta(artifactsTeamName);
+        if (meta.session_id) {
+          // Legacy team with session_id - redirect to session directory
+          const legacySessionDir = getSessionDir(meta.session_id, root);
+          if (existsSync(legacySessionDir)) {
+            serveArtifacts(legacySessionDir, meta.session_id, meta, artifactPath, res);
+            return true;
+          }
+        }
+
+        jsonResponse(res, 200, {
+          tree: [],
+          sessionId: null,
+          message: 'Session directory not found'
+        });
+        return true;
+      }
+
+      // Direct session access - artifacts are siblings of .msg/
+      const meta = getEffectiveTeamMeta(artifactsTeamName);
+      serveArtifacts(sessionDir, artifactsTeamName, meta, artifactPath, res);
      return true;
    } catch (error) {
      jsonResponse(res, 500, { error: (error as Error).message });
@@ -142,8 +462,6 @@ export async function handleTeamRoutes(ctx: RouteContext): Promise<boolean> {
  }

  // ====== GET /api/teams/:name/messages or /api/teams/:name/status ======
-  if (req.method !== 'GET') return false;
-
  const match = pathname.match(/^\/api\/teams\/([^/]+)\/(messages|status)$/);
  if (!match) return false;

@@ -208,3 +526,117 @@ export async function handleTeamRoutes(ctx: RouteContext): Promise<boolean> {

  return false;
 }
+
+/**
+ * Serve artifacts from session directory
+ */
+function serveArtifacts(
+  sessionDir: string,
+  sessionId: string,
+  meta: TeamMeta,
+  artifactPath: string | null,
+  res: import('http').ServerResponse
+): void {
+  // If specific file path requested
+  if (artifactPath) {
+    const filePath = join(sessionDir, artifactPath);
+
+    if (!existsSync(filePath)) {
+      jsonResponse(res, 404, {
+        error: 'Artifact not found',
+        path: artifactPath
+      });
+      return;
+    }
+
+    const stat = statSync(filePath);
+
+    if (stat.isDirectory()) {
+      // Return directory listing
+      const children = scanArtifactsDirectory(filePath, artifactPath);
+      jsonResponse(res, 200, {
+        type: 'directory',
+        name: artifactPath.split('/').pop() || '',
+        path: artifactPath,
+        children,
+        modifiedAt: stat.mtime.toISOString()
+      });
+      return;
+    }
+
+    // Return file content
+    const content = readFileSync(filePath, 'utf-8');
+    const contentType = detectContentType(artifactPath.split('/').pop() || '');
+
+    jsonResponse(res, 200, {
+      type: 'file',
+      name: artifactPath.split('/').pop() || '',
+      path: artifactPath,
+      contentType,
+      size: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+      content
+    });
+    return;
+  }
+
+  // Return full artifacts tree
+  const tree = scanArtifactsDirectory(sessionDir, '');
+
+  jsonResponse(res, 200, {
+    teamName: sessionId,
+    sessionId: sessionId,
+    sessionPath: sessionDir,
+    pipelineMode: meta.pipeline_mode,
+    tree,
+    totalFiles: countFiles(tree),
+    totalDirectories: countDirectories(tree),
+    totalSize: countTotalSize(tree)
+  });
+}
+
+/**
+ * Count total files in artifact tree
+ */
+function countFiles(nodes: ArtifactNode[]): number {
+  let count = 0;
+  for (const node of nodes) {
+    if (node.type === 'file') {
+      count++;
+    } else if (node.children) {
+      count += countFiles(node.children);
+    }
+  }
+  return count;
+}
+
+/**
+ * Count total directories in artifact tree
+ */
+function countDirectories(nodes: ArtifactNode[]): number {
+  let count = 0;
+  for (const node of nodes) {
+    if (node.type === 'directory') {
+      count++;
+      if (node.children) {
+        count += countDirectories(node.children);
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Count total size of all files in artifact tree
+ */
+function countTotalSize(nodes: ArtifactNode[]): number {
+  let totalSize = 0;
+  for (const node of nodes) {
+    if (node.type === 'file' && node.size) {
+      totalSize += node.size;
+    } else if (node.children) {
+      totalSize += countTotalSize(node.children);
+    }
+  }
+  return totalSize;
+}
--- a/ccw/src/tools/cli-output-converter.ts
+++ b/ccw/src/tools/cli-output-converter.ts
@@ -788,17 +788,22 @@ export class JsonLinesParser implements IOutputParser {

    // Default: treat as stdout/stderr based on fallback
    if (json.content || json.message || json.text) {
+      const rawContent = json.content || json.message || json.text;
+      // Safely convert to string: content may be an array (e.g. Claude API content blocks) or object
+      const contentStr = typeof rawContent === 'string'
+        ? rawContent
+        : JSON.stringify(rawContent);
      this.debugLog('mapJsonToIR_fallback_stdout', {
        type: json.type,
        fallbackType: fallbackStreamType,
        hasContent: !!json.content,
        hasMessage: !!json.message,
        hasText: !!json.text,
-        contentPreview: (json.content || json.message || json.text || '').substring(0, 100)
+        contentPreview: contentStr.substring(0, 100)
      });
      return {
        type: fallbackStreamType,
-        content: json.content || json.message || json.text,
+        content: contentStr,
        timestamp
      };
    }
--- a/ccw/src/tools/team-msg.ts
+++ b/ccw/src/tools/team-msg.ts
@@ -24,6 +24,7 @@ export interface TeamMeta {
  updated_at: string;
  archived_at?: string;
  pipeline_mode?: string;
+  session_id?: string;  // Links to .workflow/.team/{session-id}/ artifacts directory
 }

 export function getMetaPath(team: string): string {
@@ -106,7 +107,7 @@ export interface StatusEntry {

 const ParamsSchema = z.object({
  operation: z.enum(['log', 'read', 'list', 'status', 'delete', 'clear']).describe('Operation to perform'),
-  team: z.string().describe('Team name (maps to .workflow/.team-msg/{team}/messages.jsonl)'),
+  team: z.string().describe('Session ID (new: .workflow/.team/{session-id}/.msg/) or team name (legacy: .workflow/.team-msg/{team}/)'),

  // log params
  from: z.string().optional().describe('[log/list] Sender role name'),
@@ -121,6 +122,9 @@ const ParamsSchema = z.object({

  // list params
  last: z.number().min(1).max(100).optional().describe('[list] Return last N messages (default: 20)'),
+
+  // session_id for artifact discovery
+  session_id: z.string().optional().describe('[log] Session ID for artifact discovery (links team to .workflow/.team/{session-id}/)'),
 });

 type Params = z.infer<typeof ParamsSchema>;
@@ -131,14 +135,21 @@ export const schema: ToolSchema = {
  name: 'team_msg',
  description: `Team message bus - persistent JSONL log for Agent Team communication.

+Directory Structure (NEW):
+  .workflow/.team/{session-id}/.msg/messages.jsonl
+
+Directory Structure (LEGACY):
+  .workflow/.team-msg/{team-name}/messages.jsonl
+
 Operations:
-  team_msg(operation="log", team="my-team", from="planner", to="coordinator", type="plan_ready", summary="Plan ready: 3 tasks", ref=".workflow/.team-plan/my-team/plan.json")
-  team_msg(operation="read", team="my-team", id="MSG-003")
-  team_msg(operation="list", team="my-team")
-  team_msg(operation="list", team="my-team", from="tester", last=5)
-  team_msg(operation="status", team="my-team")
-  team_msg(operation="delete", team="my-team", id="MSG-003")
-  team_msg(operation="clear", team="my-team")
+  team_msg(operation="log", team="TLS-my-team-2026-02-15", from="planner", to="coordinator", type="plan_ready", summary="Plan ready: 3 tasks", ref=".workflow/.team-plan/my-team/plan.json")
+  team_msg(operation="log", team="TLS-my-team-2026-02-15", from="coordinator", to="implementer", type="task_unblocked", summary="Task ready")
+  team_msg(operation="read", team="TLS-my-team-2026-02-15", id="MSG-003")
+  team_msg(operation="list", team="TLS-my-team-2026-02-15")
+  team_msg(operation="list", team="TLS-my-team-2026-02-15", from="tester", last=5)
+  team_msg(operation="status", team="TLS-my-team-2026-02-15")
+  team_msg(operation="delete", team="TLS-my-team-2026-02-15", id="MSG-003")
+  team_msg(operation="clear", team="TLS-my-team-2026-02-15")

 Message types: plan_ready, plan_approved, plan_revision, task_unblocked, impl_complete, impl_progress, test_result, review_result, fix_required, error, shutdown`,
  inputSchema: {
@@ -161,6 +172,7 @@ Message types: plan_ready, plan_approved, plan_revision, task_unblocked, impl_co
      data: { type: 'object', description: '[log] Optional structured data' },
      id: { type: 'string', description: '[read] Message ID (e.g. MSG-003)' },
      last: { type: 'number', description: '[list] Last N messages (default 20)', minimum: 1, maximum: 100 },
+      session_id: { type: 'string', description: '[log] Session ID for artifact discovery' },
    },
    required: ['operation', 'team'],
  },
@@ -168,9 +180,26 @@ Message types: plan_ready, plan_approved, plan_revision, task_unblocked, impl_co

 // --- Helpers ---

-export function getLogDir(team: string): string {
+/**
+ * Get the log directory for a session.
+ * New structure: .workflow/.team/{session-id}/.msg/
+ */
+export function getLogDir(sessionId: string): string {
  const root = getProjectRoot();
-  return join(root, '.workflow', '.team-msg', team);
+  return join(root, '.workflow', '.team', sessionId, '.msg');
+}
+
+/**
+ * Legacy support: Check both new (.team/{id}/.msg) and old (.team-msg/{id}) locations
+ */
+export function getLogDirWithFallback(sessionId: string): string {
+  const newPath = getLogDir(sessionId);
+  if (existsSync(newPath)) {
+    return newPath;
+  }
+  // Fallback to old location for backward compatibility
+  const root = getProjectRoot();
+  return join(root, '.workflow', '.team-msg', sessionId);
 }

 function getLogPath(team: string): string {
@@ -241,6 +270,14 @@ function opLog(params: Params): ToolResult {

  appendFileSync(logPath, JSON.stringify(msg) + '\n', 'utf-8');

+  // Update meta with session_id if provided
+  if (params.session_id) {
+    const meta = getEffectiveTeamMeta(params.team);
+    meta.session_id = params.session_id;
+    meta.updated_at = nowISO();
+    writeTeamMeta(params.team, meta);
+  }
+
  return { success: true, result: { id, message: `Logged ${id}: [${msg.from} → ${msg.to}] ${msg.summary}` } };
 }