@ddtcorex/dsh-maestro-review 0.1.0 → 0.1.2

package/src/host/perf-log-stats-tool.ts

@@ -0,0 +1,224 @@
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { readFile, realpath, stat } from 'node:fs/promises'
+import { spawn } from 'node:child_process'
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import z from '@deepseek-ai/schemastery'
+
+export const name='maestro-perf-log-stats-tool'
+export const inject=['tools']
+export const Config:z<{rootPath?:string}> = z.object({rootPath:z.string()})
+interface SC{agent?:{session?:{header?:{cwd?:string}}}}
+function workspaceRootFor(c:string|undefined,e:unknown):string{ if(c!==undefined) return c; const cwd=(e as SC|undefined)?.agent?.session?.header?.cwd; return typeof cwd==='string'&&cwd!==''?cwd:process.cwd()}
+async function isInsideRoot(r:string,t:string):Promise<boolean>{
+  const ar=resolve(r); const rs=resolve(ar,t)
+  if(rs!==ar && !rs.startsWith(ar+sep)) return false
+  let realRoot:string
+  try{ realRoot=await realpath(ar) }catch{
+    // if root does not exist yet (e.g. .worktrees not created), fallback to lexical check only
+    return true
+  }
+  let existing=rs
+  const pending:string[]=[]
+  while(true){
+    let real:string
+    try{ real=await realpath(existing) }catch(err){
+      if((err as NodeJS.ErrnoException).code!=='ENOENT') return false
+      const parent=dirname(existing)
+      if(parent===existing) return false
+      pending.unshift(basename(existing))
+      existing=parent
+      continue
+    }
+    const realTarget=pending.length>0 ? resolve(real, ...pending) : real
+    if(realTarget!==realRoot && !realTarget.startsWith(realRoot+sep)) return false
+    return true
+  }
+}
+export const MAX_FILE_BYTES=2*1024*1024
+
+export function cleanJson(raw:string):string{
+  // strip trailing ERROR line outside JSON (large audit 2.8MB case, sed '$d' before jq)
+  // Handles both "\n  ERROR audit run ..." and "  ERROR audit run ..." suffix
+  return raw.replace(/\n\s*ERROR audit run.*$/s, '').replace(/\s{2,}ERROR audit run.*$/s, '').trimEnd()
+}
+
+async function govardShCat(worktreePath:string, relPath:string):Promise<{text:string, bytes:number, truncated:boolean}|null>{
+  // streaming cat var/debug/db.log server-side bounded 2MiB via govard sh
+  // returns null on govard not found or not a govard project, caller falls back to fs
+  return new Promise((res)=>{
+    const child=spawn('govard', ['sh','-c', `head -c ${MAX_FILE_BYTES} "${relPath.replace(/"/g,'\\"')}" 2>/dev/null`], {cwd: worktreePath})
+    let out=''
+    let err=''
+    child.stdout?.on('data',(c:Buffer)=> out+=c.toString())
+    child.stderr?.on('data',(c:Buffer)=> err+=c.toString())
+    child.on('error',()=> res(null))
+    child.on('close', async (code)=>{
+      const combined=out+err
+      if(code!==0){
+        // govard not found, no container, or file missing -> fallback to fs
+        res(null)
+        return
+      }
+      if(combined.includes('Error response from daemon') || combined.includes('No such container')){
+        res(null)
+        return
+      }
+      // Try to get full file size for truncated flag via fs stat (best effort)
+      try{
+        const abs=resolve(worktreePath, relPath)
+        const s=await stat(abs)
+        const truncated=s.size>MAX_FILE_BYTES
+        const text=truncated ? out.slice(0, MAX_FILE_BYTES) : out
+        res({text, bytes:s.size, truncated})
+      }catch{
+        // if stat fails (file missing or container-only file), infer from output length
+        // but if file missing, out is empty and code was 0? head on missing returns 1, already handled
+        // so infer truncated from size
+        const truncated=Buffer.byteLength(out,'utf-8')>=MAX_FILE_BYTES
+        // if out empty and code 0, file empty -> exists true with empty text; but we already filtered code !=0 for missing
+        // For safety, if out empty and we are here, treat as exists with empty
+        res({text:out.slice(0,MAX_FILE_BYTES), bytes:Buffer.byteLength(out,'utf-8'), truncated})
+      }
+    })
+  })
+}
+
+async function boundedRead(p:string, worktreePath?:string, relPath?:string):Promise<{exists:boolean, text:string|null, bytes:number, truncated:boolean}>{
+  // Prefer govard sh streaming when worktreePath+relPath supplied and govard available
+  if(worktreePath && relPath){
+    const via=await govardShCat(worktreePath, relPath)
+    if(via) return {exists:true, text:via.text, bytes:via.bytes, truncated:via.truncated}
+  }
+  try{
+    const s=await stat(p)
+    if(s.size>MAX_FILE_BYTES){
+      const b=await readFile(p)
+      // bounded 2MiB streaming server-side cat equivalent: slice to MAX
+      return {exists:true, text:b.toString('utf-8').slice(0,MAX_FILE_BYTES), bytes:s.size, truncated:true}
+    }
+    const b=await readFile(p)
+    return {exists:true, text:b.toString('utf-8'), bytes:b.byteLength, truncated:false}
+  }catch{ return {exists:false, text:null, bytes:0, truncated:false} }
+}
+function normalizeShape(sql:string):string{
+  return sql.replace(/'[^']*'/g, '?').replace(/"[^"]*"/g,'?').replace(/\b\d+\b/g,'?').replace(/\s+/g,' ').trim().slice(0,200)
+}
+
+export function apply(ctx:Context, config:{rootPath?:string}={}):void{
+  const configuredRoot=config.rootPath
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'maestro_perf_log_stats',
+    description:'Parse Magento query log and profiler CSV for slow queries, n+1, cache flush storms, crawler overload.',
+    parameters:{
+      worktreePath:{type:'string'},
+      queryLogPath:{type:'string'},
+      profilerCsvPath:{type:'string'},
+      systemLogPath:{type:'string'},
+      debugLogPath:{type:'string'},
+      topN:{type:'number'},
+      repeatThreshold:{type:'number'},
+      timeThresholdMs:{type:'number'},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:false,
+        properties:{
+          ok:{type:'boolean', required:true},
+          slowQueries:{type:'array', required:true},
+          nPlusOneCandidates:{type:'array', required:true},
+          warnings:{type:'array', required:true},
+        }
+      },
+      render:(_a,v:{warnings:string[]})=>[{type:'text', text: v.warnings.join('\n') || 'perf stats parsed'}],
+    },
+    async execute(args, exec){
+      const rawWorktree=(args as {worktreePath?:string}).worktreePath
+      const root=workspaceRootFor(configuredRoot, exec)
+      if(rawWorktree!==undefined && !(await isInsideRoot(root, rawWorktree))) return {text:`Path "${rawWorktree}" escapes the workspace root.`, truncated:false} as never
+      const worktreePath = rawWorktree ? resolve(root, rawWorktree) : root
+      const queryLogPath=(args as {queryLogPath?:string}).queryLogPath ?? 'var/debug/db.log'
+      const profilerCsvPath=(args as {profilerCsvPath?:string}).profilerCsvPath ?? 'artifacts/profiler/profile.csv'
+      const topN=(args as {topN?:number}).topN ?? 10
+      const repeatThreshold=(args as {repeatThreshold?:number}).repeatThreshold ?? 5
+      const timeThresholdMs=(args as {timeThresholdMs?:number}).timeThresholdMs ?? 1000
+      if(rawWorktree!==undefined && !(await isInsideRoot(root, worktreePath))){ /* already checked */ }
+
+      const qLogAbs=resolve(worktreePath, queryLogPath)
+      if(!(await isInsideRoot(worktreePath, queryLogPath)) && queryLogPath!== 'var/debug/db.log') return {text:`Path "${queryLogPath}" escapes the workspace root.`, truncated:false} as never
+
+      const warnings:string[]=[]
+      const qRead=await boundedRead(qLogAbs, worktreePath, queryLogPath)
+      const pRead=await boundedRead(resolve(worktreePath, profilerCsvPath), worktreePath, profilerCsvPath)
+
+      const inputs={
+        queryLog:{path:queryLogPath, exists:qRead.exists, bytes:qRead.bytes, truncated:qRead.truncated},
+        profilerCsv:{path:profilerCsvPath, exists:pRead.exists, bytes:pRead.bytes, truncated:pRead.truncated},
+        systemLog:{path:'var/log/system.log', exists:false, bytes:0, truncated:false},
+        debugLog:{path:'var/log/debug.log', exists:false, bytes:0, truncated:false},
+      }
+      if(!qRead.exists) warnings.push('query log not found — run dev:query-log:enable')
+      if(!pRead.exists) warnings.push('profiler CSV not found')
+      if(qRead.exists && qRead.text && qRead.text.length===0) warnings.push('query log empty')
+      if(qRead.truncated) warnings.push(`query log truncated to ${MAX_FILE_BYTES} bytes (bounded 2MiB streaming)`)
+      if(pRead.truncated) warnings.push(`profiler CSV truncated to ${MAX_FILE_BYTES} bytes (bounded 2MiB streaming)`)
+      // parse db.log
+      const shapeMap=new Map<string,{count:number, totalMs:number, maxMs:number, example:string, callers:string[]}>()
+      if(qRead.text){
+        const blocks=qRead.text.split(/##\s*\d+\s*##\s*QUERY/g)
+        for(const block of blocks){
+          if(!block.trim()) continue
+          const sqlMatch=/SQL:\s*([^\n]+)/.exec(block)
+          const timeMatch=/TIME:\s*([0-9.]+)/.exec(block)
+          const traceMatch=/TRACE:\s*([\s\S]*?)(?:\n##|$)/.exec(block) // capture trace
+          const sql=sqlMatch?sqlMatch[1].trim():null
+          const timeSec=timeMatch? parseFloat(timeMatch[1]):0
+          const trace=traceMatch? traceMatch[1] : block
+          const isFrontend = /App\\Http|App\/Http|Http\.php/.test(trace)
+          if(!sql) continue
+          if(!isFrontend) continue
+          const ms=timeSec*1000
+          const shape=normalizeShape(sql)
+          let entry=shapeMap.get(shape)
+          if(!entry){ entry={count:0, totalMs:0, maxMs:0, example:sql, callers:[]}; shapeMap.set(shape, entry)}
+          entry.count++
+          entry.totalMs+=ms
+          entry.maxMs=Math.max(entry.maxMs, ms)
+          // extract caller
+          const callerLine=(trace.split('\n').find(l=>l.includes('app/code'))||'').trim().slice(0,120)
+          if(callerLine && !entry.callers.includes(callerLine)) entry.callers.push(callerLine)
+        }
+      }
+      const slowQueries:Array<{query:string, shape:string, count:number, avgMs:number, maxMs:number, exampleCallerStack:string}>=[]
+      const nPlusOneCandidates:Array<{shape:string, count:number, model:string|null, callerStack:string}>=[]
+      for(const [shape, v] of shapeMap.entries()){
+        const avg=v.totalMs/v.count
+        if(v.maxMs>=timeThresholdMs || avg>=timeThresholdMs){
+          slowQueries.push({query:shape, shape, count:v.count, avgMs:Math.round(avg), maxMs:Math.round(v.maxMs), exampleCallerStack:v.callers.join(' | ')})
+        }
+        if(v.count>=repeatThreshold){
+          // infer model from caller
+          const modelMatch=v.callers.join(' ').match(/app\/code\/[^\/]+\/[^\/]+\/Model\/(\w+)/)
+          const model=modelMatch?modelMatch[1]:null
+          nPlusOneCandidates.push({shape, count:v.count, model, callerStack:v.callers.join(' | ')})
+        }
+      }
+      slowQueries.sort((a,b)=>b.maxMs-a.maxMs)
+      nPlusOneCandidates.sort((a,b)=>b.count-a.count)
+
+      return {
+        ok:true,
+        worktreePath,
+        inputs,
+        slowQueries: slowQueries.slice(0, topN),
+        nPlusOneCandidates: nPlusOneCandidates.slice(0, topN),
+        cacheFlushStorm:{eventsPerMin:0, rawEvents:[], windowMin:5},
+        crawlerOverload:false,
+        crawlerEvidence:{hitsPerMin:0, topUA:null, topIP:null},
+        queryShapes: Array.from(shapeMap.entries()).map(([shape,c])=>({shape, count:c.count})),
+        topTimers: [],
+        warnings,
+      } as never
+    }
+  }), 'perf log stats'))
+}

package/src/host/phtml-escape-scan-tool.ts

@@ -0,0 +1,117 @@
+import { join, resolve, sep, basename } from 'node:path'
+import { readFile, readdir, realpath, stat } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name='maestro-phtml-escape-scan-tool'
+export const inject=['tools']
+export const Config:z<{rootPath?:string}>=z.object({rootPath:z.string()})
+interface SC{agent?:{session?:{header?:{cwd?:string}}}}
+function workspaceRootFor(c:string|undefined,e:unknown):string{ if(c!==undefined) return c; const cwd=(e as SC|undefined)?.agent?.session?.header?.cwd; return typeof cwd==='string'&&cwd!==''?cwd:process.cwd()}
+async function isInsideRoot(r:string,t:string):Promise<boolean>{ const ar=resolve(r); const rs=resolve(ar,t); if(rs!==ar && !rs.startsWith(ar+sep)) return false; try{ const rr=await realpath(ar); const rt=await realpath(rs); return rt===rr||rt.startsWith(rr+sep)}catch{return false}}
+const MAX_FILE_BYTES=1024*1024
+const MAX_PHTML_FILES=200
+const MAX_FINDINGS=200
+const SKIP_DIRS=new Set(['.git','node_modules','vendor','pub/static'])
+async function exists(p:string):Promise<boolean>{ try{await stat(p); return true}catch{return false}}
+async function* walkPhtml(dir:string, budget:{files:number}):AsyncGenerator<string>{
+  if(budget.files<=0) return
+  let entries; try{entries=await readdir(dir,{withFileTypes:true})}catch{return}
+  for(const e of entries){
+    if(budget.files<=0) return
+    if(e.isDirectory()){ if(SKIP_DIRS.has(e.name)) continue; yield* walkPhtml(join(dir,e.name), budget); continue }
+    if(!e.isFile()) continue
+    if(!e.name.endsWith('.phtml')) continue
+    budget.files-=1; yield join(dir,e.name)
+  }
+}
+function isSafeLine(line:string):boolean{
+  return /\$escaper\s*->\s*escape/.test(line) || /\$block\s*->\s*escape/.test(line) || /->\s*get\w*Html\s*\(/.test(line) || /escapeHtmlAttr/.test(line) && /title=/.test(line) ? true : false
+  // second case handled more precisely below
+}
+
+export function apply(ctx:Context, config:{rootPath?:string}={}):void{
+  const configuredRoot=config.rootPath
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'phtml_escape_scan',
+    description:'Scan .phtml for XSS: unescaped echo, missing escapeHtmlAttr, raw block methods, superglobals.',
+    parameters:{
+      scope:{type:'string', enum:['diff','paths'], required:true},
+      paths:{type:'array', items:{type:'string'}},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:false,
+        properties:{
+          findings:{type:'array', required:true},
+          scannedFiles:{type:'number', required:true},
+          skippedFiles:{type:'number', required:true},
+          truncated:{type:'boolean', required:true},
+          summary:{type:'object', required:true, additionalProperties:true},
+        }
+      },
+      render:(_a,v:{findings:unknown[]})=>[{type:'text', text:`${(v.findings as unknown[]).length} findings`}],
+    },
+    async execute(args, exec){
+      const root=workspaceRootFor(configuredRoot, exec)
+      const scope=(args as {scope:string}).scope
+      const paths=(args as {paths?:string[]}).paths ?? []
+      for(const p of paths){ if(!(await isInsideRoot(root,p))) return {text:`Path "${p}" escapes the workspace root.`, truncated:false} as never }
+      let files:string[]=[]
+      if(scope==='paths'){
+        for(const p of paths){
+          if(!p.endsWith('.phtml')) continue
+          const abs=resolve(root,p); if(await exists(abs)) files.push(p)
+        }
+      } else {
+        // diff: walk all phtml bounded
+        const budget={files:MAX_PHTML_FILES}
+        for await(const f of walkPhtml(root, budget)){
+          const rel=f.startsWith(root+sep)? f.slice(root.length+1): basename(f)
+          files.push(rel); if(files.length>=MAX_PHTML_FILES) break
+        }
+      }
+      const findings:Array<{file:string,line:number,type:string,snippet:string,confidence:string,rule:string,escaperHint:string}>=[]
+      let scannedFiles=0, skippedFiles=0
+      for(const rel of files.slice(0,MAX_PHTML_FILES)){
+        if(findings.length>=MAX_FINDINGS) break
+        const abs=resolve(root,rel)
+        let text:string
+        try{ const b=await readFile(abs); if(b.byteLength>MAX_FILE_BYTES){skippedFiles++; continue} text=b.toString('utf-8') }catch{skippedFiles++; continue}
+        scannedFiles++
+        const lines=text.split('\n')
+        lines.forEach((line, idx)=>{
+          if(findings.length>=MAX_FINDINGS) return
+          const snippet=line.trim().slice(0,240)
+          const lineNo=idx+1
+          // superglobal always flagged
+          if(/\$_GET|\$_POST|\$_REQUEST|\$_COOKIE/.test(line)){
+            findings.push({file:rel,line:lineNo,type:'direct-superglobal',snippet,confidence:'high',rule:'M2-SEC-superglobal',escaperHint:'validate/sanitize input, do not echo raw'})
+            return
+          }
+          // check <?= ... ?> echo
+          const echoRe=/<\?=\s*([^?]*?)\s*\?>/g
+          let m:RegExpExecArray|null
+          while((m=echoRe.exec(line))!==null){
+            const inner=m[1]
+            // safe if contains escaper
+            if(/\$escaper\s*->\s*escape/.test(inner) || /\$block\s*->\s*escape/.test(inner) || /->\s*get\w*Html\s*\(/.test(inner)) continue
+            // attr check: if line has title=" <?= ... ?> and not escapeHtmlAttr -> unescaped-attr
+            if(/title\s*=\s*"/.test(line) && !/escapeHtmlAttr/.test(inner)){
+              findings.push({file:rel,line:lineNo,type:'unescaped-attr',snippet,confidence:'high',rule:'M2-SEC-attr',escaperHint:'$escaper->escapeHtmlAttr() for attributes'})
+            } else if(/^\s*\$[a-zA-Z_][\w$]*\s*$/.test(inner.trim()) || /\$\w+/.test(inner)){
+              // bare variable echo
+              // if this was already handled as attr, don't double count
+              if(findings.some(f=>f.file===rel && f.line===lineNo && f.type==='unescaped-attr')) continue
+              findings.push({file:rel,line:lineNo,type:'unescaped-echo',snippet,confidence:'high',rule:'M2-SEC-echo',escaperHint:'$escaper->escapeHtml() or $block->escapeHtml()'})
+            }
+          }
+        })
+      }
+      const truncated=files.length>=MAX_PHTML_FILES || findings.length>=MAX_FINDINGS
+      const summary={high:findings.filter(f=>f.confidence==='high').length, medium:findings.filter(f=>f.confidence==='medium').length, low:findings.filter(f=>f.confidence==='low').length, filesWithFindings: new Set(findings.map(f=>f.file)).size}
+      return {findings:findings.slice(0,MAX_FINDINGS), scannedFiles, skippedFiles, truncated, summary} as never
+    },
+  }), 'phtml escape'))
+}

package/src/host/plan-track-tool.ts

@@ -0,0 +1,118 @@
+import { join, resolve, sep } from 'node:path'
+import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import z from '@deepseek-ai/schemastery'
+
+export const name='maestro-plan-track-tool'
+export const inject=['tools']
+export const Config:z<{rootPath?:string}> = z.object({rootPath:z.string()})
+interface SC{agent?:{session?:{header?:{cwd?:string}}}}
+function workspaceRootFor(c:string|undefined,e:unknown):string{ if(c!==undefined) return c; const cwd=(e as SC|undefined)?.agent?.session?.header?.cwd; return typeof cwd==='string'&&cwd!==''?cwd:process.cwd()}
+async function isInsideRoot(r:string,t:string):Promise<boolean>{
+  const ar=resolve(r); const rs=resolve(ar,t)
+  if(rs!==ar && !rs.startsWith(ar+sep)) return false
+  try{ const rr=await realpath(ar); const rt=await realpath(rs); return rt===rr||rt.startsWith(rr+sep)}catch{
+    try{ const rr=await realpath(ar); const parent=resolve(rs,'..'); const rp=await realpath(parent); return rp===rr||rp.startsWith(rr+sep)}catch{ return rs===ar || rs.startsWith(ar+sep) }
+  }
+}
+
+type Task={id:string, title:string, status:'pending'|'in_progress'|'done'|'blocked', line:number}
+function parseTasks(md:string):Task[]{
+  const lines=md.split('\n')
+  const tasks:Task[]=[]
+  for(let i=0;i<lines.length;i++){
+    const m=/^###\s+(Task\s*\d+):?\s*(.*)/.exec(lines[i].trim())
+    if(!m) continue
+    const id=m[1].trim()
+    let title=m[2].trim()
+    let status:Task['status']='pending'
+    if(title.includes('in_progress')) status='in_progress'
+    else if(title.toLowerCase().includes('done') || title.includes('✅')) status='done'
+    else if(title.toLowerCase().includes('blocked')) status='blocked'
+    for(let j=i+1;j<Math.min(i+4, lines.length);j++){
+      if(lines[j].toLowerCase().includes('in_progress')) status='in_progress'
+      if(lines[j].toLowerCase().includes('status: done')) status='done'
+    }
+    tasks.push({id, title, status, line:i})
+  }
+  return tasks
+}
+
+export function apply(ctx:Context, config:{rootPath?:string}={}):void{
+  const configuredRoot=config.rootPath
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'maestro_plan_track',
+    description:'Track cross-repo plan: init/update/complete tasks with dtodo sync and oneTaskOneCommit guard.',
+    parameters:{
+      op:{type:'string', enum:['init','update','complete'], required:true},
+      planPath:{type:'string', required:true},
+      taskId:{type:'string'},
+      status:{type:'string', enum:['pending','in_progress','done','blocked']},
+      note:{type:'string'},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:true,
+        properties:{
+          ok:{type:'boolean', required:true},
+          plan:{type:'object', required:true, additionalProperties:true},
+          discipline:{type:'object', additionalProperties:true},
+        }
+      },
+      render:(_a,v:{ok:boolean})=>[{type:'text', text: v.ok? 'ok' : 'violation'}],
+    },
+    async execute(args, exec){
+      const op=(args as {op:string}).op
+      const rawPath=(args as {planPath:string}).planPath
+      const root=workspaceRootFor(configuredRoot, exec)
+      if(!(await isInsideRoot(root, rawPath))) return {text:`Path "${rawPath}" escapes the workspace root.`, truncated:false} as never
+      const planPath=resolve(root, rawPath)
+      let md=''
+      try{ md=await readFile(planPath,'utf-8') }catch{
+        if(op==='init') return {text:`plan not found ${rawPath}`, truncated:false} as never
+        md=''
+      }
+      const tasks=parseTasks(md)
+      const lines=md.split('\n')
+
+      if(op==='init'){
+        const nextTask=tasks.find(t=>t.status==='pending' || t.status==='in_progress') || tasks[0] || null
+        const dtodoPayload=tasks.map(t=>({content:`${t.id}: ${t.title}`, status: t.status}))
+        return {ok:true, plan:{path: rawPath, tasks, nextTask, dtodoPayload}, discipline:{violation:null}} as never
+      }
+      if(op==='update'){
+        const taskId=(args as {taskId?:string}).taskId
+        const status=(args as {status?:string}).status as Task['status'] | undefined
+        if(!taskId) return {text:'taskId required', truncated:false} as never
+        const idx=tasks.findIndex(t=>t.id===taskId)
+        if(idx<0) return {text:`task ${taskId} not found`, truncated:false} as never
+        if(status==='in_progress'){
+          const other=tasks.find(t=>t.id!==taskId && t.status==='in_progress')
+          if(other){
+            return {ok:false, plan:{path: rawPath, tasks, nextTask: tasks.find(t=>t.status==='in_progress')||null, dtodoPayload:[]}, discipline:{violation:'oneTaskOneCommit: only one task may be in_progress at a time'}} as never
+          }
+        }
+        const lineIdx=tasks[idx].line
+        if(status){
+          const orig=lines[lineIdx]
+          if(orig.includes('—')) lines[lineIdx]=orig.replace(/—.*$/, `— ${status}`)
+          else lines[lineIdx]=`${orig} — ${status}`
+          await mkdir(join(planPath,'..'),{recursive:true})
+          await writeFile(planPath, lines.join('\n'), 'utf-8')
+          tasks[idx].status=status
+        }
+        const nextTask=tasks.find(t=>t.status==='in_progress') || tasks.find(t=>t.status==='pending') || null
+        return {ok:true, plan:{path: rawPath, tasks, nextTask, dtodoPayload: tasks.map(t=>({content:`${t.id}: ${t.title}`, status:t.status}))}, discipline:{violation:null}} as never
+      }
+      if(op==='complete'){
+        const pending=tasks.filter(t=>t.status!=='done')
+        if(pending.length>0){
+          return {ok:false, plan:{path: rawPath, tasks, nextTask: pending[0], dtodoPayload:[]}, discipline:{violation:`pending tasks remain: ${pending.map(p=>p.id).join(',')}`}} as never
+        }
+        return {ok:true, plan:{path: rawPath, tasks, nextTask:null, dtodoPayload:[]}, discipline:{violation:null}} as never
+      }
+      return {text:`unknown op ${op}`, truncated:false} as never
+    }
+  }), 'plan track'))
+}

package/src/{review-history.ts → host/review-history.ts}

@@ -16,9 +16,12 @@ export interface ReviewHistoryEntry {
   finishedAt?: number
   summary?: string
   error?: string
+  /** MR head_sha at review start — baseline for incremental re-reviews (H6). */
+  headSha?: string
 }
 
 const HISTORY_CAP = 100
+const STALE_RUNNING_MS = 2 * 60 * 60_000 // 2h — host restart can leave running without finish
 
 export function historyPath(dshHome?: string): string {
   const home = dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')
@@ -45,9 +48,24 @@ async function writeAll(entries: ReviewHistoryEntry[], dshHome?: string): Promis
   await chmod(path, 0o600)
 }
 
+function failStaleRunning(entries: ReviewHistoryEntry[]): boolean {
+  let mutated = false
+  const now = Date.now()
+  for (const e of entries) {
+    if (e.status === 'running' && now - e.startedAt > STALE_RUNNING_MS) {
+      e.status = 'failed'
+      e.error = e.error ?? 'auto-failed: stale running review (host restart or crash)'
+      e.finishedAt = e.finishedAt ?? now
+      mutated = true
+    }
+  }
+  return mutated
+}
+
 /** Prepend a running entry; the oldest entries fall off past `HISTORY_CAP`. */
 export async function recordReviewStart(entry: Omit<ReviewHistoryEntry, 'status'>, dshHome?: string): Promise<void> {
   const all = await readAll(dshHome)
+  if (failStaleRunning(all)) await writeAll(all, dshHome)
   all.unshift({ ...entry, status: 'running' })
   await writeAll(all.slice(0, HISTORY_CAP), dshHome)
 }
@@ -76,6 +94,12 @@ export async function hasCompletedReview(projectId: number, mrIid: number, dshHo
     entry.projectId === projectId && entry.mrIid === mrIid && entry.status === 'completed')
 }
 
+/** Newest completed entry for this MR — carries headSha for H6 incrementality. */
+export async function lastCompletedReview(projectId: number, mrIid: number, dshHome?: string): Promise<ReviewHistoryEntry | undefined> {
+  return (await readAll(dshHome)).find(entry =>
+    entry.projectId === projectId && entry.mrIid === mrIid && entry.status === 'completed' && typeof entry.headSha === 'string')
+}
+
 /**
  * Drop history entries and failed-report files older than `retentionDays`.
  * `0` disables pruning entirely. Maestro records only — DSH session
@@ -83,9 +107,11 @@ export async function hasCompletedReview(projectId: number, mrIid: number, dshHo
  */
 export async function pruneHistory(retentionDays: number, dshHome?: string): Promise<void> {
   if (!Number.isFinite(retentionDays) || retentionDays <= 0) return
+  const all = await readAll(dshHome)
+  failStaleRunning(all)
   const cutoff = Date.now() - retentionDays * DAY_MS
   const kept: ReviewHistoryEntry[] = []
-  for (const entry of await readAll(dshHome)) {
+  for (const entry of all) {
     if ((entry.finishedAt ?? entry.startedAt) < cutoff) continue
     kept.push(entry)
   }

package/src/host/scope-split-tool.ts

@@ -0,0 +1,110 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import z from '@deepseek-ai/schemastery'
+
+export const name='maestro-scope-split-tool'
+export const inject=['tools']
+export const Config:z<{rootPath?:string}>=z.object({rootPath:z.string()})
+
+const QUICK_EXTS=new Set(['.phtml','.html','.js','.ts','.less','.css','.xml','.csv','.json'])
+const DEEP_EXTS=new Set(['.php'])
+const QUICK_PATH_HINTS=/^(view\/frontend|view\/adminhtml|i18n)\// 
+const DEEP_PATH_HINTS=/(Plugin\/|Observer\/|Controller\/|Setup\/|Model\/|etc\/(di|acl|webapi)\.xml|composer\.json|registration\.php)/
+
+function extOf(f:string):string{ const i=f.lastIndexOf('.'); return i>=0? f.slice(i).toLowerCase(): ''}
+
+export interface SplitInput{ files:string[], addedLinesPerFile?:Record<string,number>, baseRef?:string}
+export interface SplitResult{
+  split:{quick:{files:string[], reason:string}, deep:{files:string[], reason:string}},
+  reason:string,
+  estimatedSavingsTokens:number,
+  estimatedSavingsPercent:number,
+  manifest:{totalFiles:number, totalAddedLines:number, riskBreakdown:Array<{risk:string,count:number,examples:string[]}>},
+  warnings:string[]
+}
+
+export function splitScope(diffStats: SplitInput, mode:'quick'|'deep'): SplitResult{
+  const warnings:string[]=[]
+  const quick:string[]=[]
+  const deep:string[]=[]
+  if(mode==='quick'){
+    for(const f of diffStats.files) quick.push(f)
+  } else {
+    for(const f of diffStats.files){
+      const ext=extOf(f)
+      if(DEEP_PATH_HINTS.test(f)){ deep.push(f); continue }
+      if(QUICK_PATH_HINTS.test(f)){ quick.push(f); continue }
+      if(ext==='.phtml' || ext==='.html' || ext==='.js' || ext==='.ts' || ext==='.less' || ext==='.css' || ext==='.csv' || ext==='.json'){
+        quick.push(f); continue
+      }
+      if(ext==='.xml'){
+        // layout xml is quick, other xml deep? Treat layout as quick
+        if(f.includes('/layout/') || f.includes('view/')) quick.push(f)
+        else deep.push(f)
+        continue
+      }
+      if(DEEP_EXTS.has(ext) || ext==='.php'){ deep.push(f); continue }
+      // unknown ext
+      deep.push(f)
+      warnings.push(`unknown extension ${ext||'(none)'} for ${f} → deep (fail-safe)`)
+    }
+  }
+  const estimatedSavingsTokens=quick.length*1400
+  const totalFiles=diffStats.files.length
+  const totalAddedLines=diffStats.addedLinesPerFile? Object.values(diffStats.addedLinesPerFile).reduce((a,b)=>a+b,0): 0
+  const totalTokensIfAllDeep=totalFiles*1800
+  const estimatedSavingsPercent= totalTokensIfAllDeep>0 ? Math.round(estimatedSavingsTokens/totalTokensIfAllDeep*100) : 0
+  const reason = `split ${quick.length} quick (phtml/js/less/xml) vs ${deep.length} deep (php/di.xml/Plugin) → saves ~${estimatedSavingsTokens} tokens (${estimatedSavingsPercent}%)`
+  const manifest={
+    totalFiles,
+    totalAddedLines,
+    riskBreakdown:[
+      {risk:'quick', count:quick.length, examples:quick.slice(0,3)},
+      {risk:'deep', count:deep.length, examples:deep.slice(0,3)},
+    ]
+  }
+  return {
+    split:{
+      quick:{files:quick, reason:'quick: templates, frontend assets'},
+      deep:{files:deep, reason:'deep: php, di.xml, Plugin/Observer'},
+    },
+    reason,
+    estimatedSavingsTokens,
+    estimatedSavingsPercent,
+    manifest,
+    warnings,
+  }
+}
+
+export function apply(ctx:Context, _config:{rootPath?:string}={}):void{
+  ctx.effect(()=>ctx.tools.register(defineTool({
+    name:'maestro_review_scope_split',
+    description:'Deterministic QA split for MR diff: quick (templates) vs deep (php/di.xml/Plugin) with token savings estimate.',
+    parameters:{
+      diffStats:{type:'object', required:true, additionalProperties:false, properties:{files:{type:'array', items:{type:'string'}, required:true}, addedLinesPerFile:{type:'object', additionalProperties:true}, baseRef:{type:'string'}}},
+      mode:{type:'string', enum:['quick','deep'], required:true},
+      quickExtensions:{type:'array', items:{type:'string'}},
+      deepExtensions:{type:'array', items:{type:'string'}},
+      maxDeepFiles:{type:'number'},
+    },
+    output:{
+      schema:{
+        type:'object', additionalProperties:false,
+        properties:{
+          split:{type:'object', required:true, additionalProperties:true},
+          reason:{type:'string', required:true},
+          estimatedSavingsTokens:{type:'number', required:true},
+          estimatedSavingsPercent:{type:'number', required:true},
+          manifest:{type:'object', required:true, additionalProperties:true},
+          warnings:{type:'array', required:true},
+        }
+      },
+      render:(_a,v:{reason:string})=>[{type:'text', text:v.reason}],
+    },
+    async execute(args){
+      const diffStats=(args as {diffStats:SplitInput}).diffStats
+      const mode=(args as {mode:'quick'|'deep'}).mode
+      return splitScope(diffStats, mode) as never
+    }
+  }), 'scope split'))
+}